InterBase Language Reference 


Delphi for Windows 

Preface 

Copyright 

Agreement 

This preface describes the documentation set, the printing conventions used to 
display information in text and in code examples, and the conventions a user 
should employ when specifying database objects and files by name in applica¬ 
tions. 


The InterBase Documentation Set 


The InterBase documentation set is an integrated package designed for all levels 
of users. The InterBase server documentation consists of a five-book core set and 
a platform-specific installation guide. Information on the InterBase Client for 
Windows is provided in a single book. 

The InterBase core documentation set consists of the following books: 


Table 1: InterBase Core Documentation 


Book 


Description 


Getting Started 


Data Definition Guide 

Language Reference 
Programmer’s Guide 

API Guide 

Installing and Running on .. . 


Provides a basic introduction to InterBase and roadmap for using the 
documentation and a tutorial for learning basic SQL through isql. 
Introduces more advanced topics such as creating stored procedures 
and triggers. 

Explains how to create, alter, and delete database objects through 

isql. 

Describes SQL and DSQL syntax and usage. 

Describes how to write embedded SQL and DSQL database applica¬ 
tions in a host language, precompiled through gpre. 

Explains how to write database applications using the InterBase API. 
Platform-specific information on installing and running InterBase. 
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Additional documentation includes the following book: 

Table 2: InterBase Client Documentation 

Book Description 

InterBase Windows Client User’s Installing and using the InterBase PC client. Using Windows isql and 
Guide the InterBase Server Manager. 


Printing Conventions 

The InterBase documentation set uses different fonts to distinguish various 
kinds of text and S5mtax. 


Text Conventions 

The following table describes font conventions used in text, and provides exam¬ 
ples of their use: 

Table 3: Text Conventions 

Convention 

Purpose 

Example 

UPPERCASE 

SQL keywords, names of all 
database objects such as 
tables, columns, indexes, 
stored procedures, and SQL 
functions. 

The following SELECT statement 
retrieves data from the CITY column in 
the CITIES table. 

italic 

Introduces new terms, and 
emphasizes words. Also 
used for file names and host- 
language variables. 

The isc4.gdb security database is not 
accessible without a valid username and 
password. 

boid 

Utility names, user-defined 
and host-language function 
names. Function names are 
always followed by paren¬ 
theses to distinguish them 
from utility names. 

To back up and restore a database, use 
gbak or the server manager. 

The datediffQ function can be used to 
calculate the number of days between two 
dates. 


Language Reference 



Syntax Conventions 

The following table describes the conventions used in S5mtax statements and 
sample code, and offers examples of their use: 

Table 4: Syntax Conventions 

Convention 

Purpose 

Example 

UPPERCASE 

Keywords that must be 
typed exactly as they appear 
when used. 

SET TERM II; 

italic 

Parameters that cannot be 
broken Into smaller units. 

For example, a table name 
cannot be subdivided. 

CREATE TABLE name 
{<col> [, <col >...]): 

<italic> 

Parameters in angle brack¬ 
ets that can be broken into 
smaller syntactic units. 

For example, column defini¬ 
tions {<col>) can be subdi¬ 
vided into a name, data type 
and constraint definition. 

CREATE TABLE name 
{<col> [, <col >...]); 

<col> = name <datatype> 

[CONSTRAINT name <type>] 

[] 

Square brackets enclose 
optional syntax. 

<col> [, <col >...] 

1 

Closely spaced ellipses Indi¬ 
cate that a clause within 
brackets can be repeated as 
many times as necessary. 
The pipe symbol indicates 
that either of two syntax 
clauses that it separates 
may be used, but not both. 
Inside curly braces, the pipe 
symbol separates multiple 
choices, one of which must 
be used. 

(<co/> [, <col >...]); 

SET TRANSACTION 
{SNAPSHOT [TABLE STABILITY] 

1 READ COMMITTED}; 

{} 

Curly braces indicate that 
one of the enclosed options 
must be included in actual 
statement use. 

SET TRANSACTION 
(SNAPSHOT [TABLE STABILITY] 

1 READ COMMITTED}; 
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Database Object-naming Conventions 

InterBase database objects, such as tables, views, and column names, appear in 
text and code in uppercase in the InterBase documentation set because this is the 
way such information is stored in a database's system tables. 

When an applications programmer or end user creates a database object or refers 
to it by name, case is unimportant. The following limitations on naming data¬ 
base objects must be observed: 

• Start each name with an alphabetic character (A-Z or a-z). 

• Restrict object names to 31 characters, including dollar signs ($), under¬ 
scores (_), 0 to 9, A to Z, and a to z. Some objects, such as constraint 
names, are restricted to 27 bytes in length. 

• Keep object names unique. In all cases, objects of the same t 5 q)e, for 
example, tables and views, must be unique. In most cases, object names 
must also be unique within the database. 


File-naming Conventions 

InterBase is available on a wide variety of platforms. In most cases users in a het¬ 
erogenous networking environment can access their InterBase database files 
regardless of platform differences between client and server machines if they 
know the target platform's file naming conventions. 

Because file-naming conventions differ widely from platform to platform, and 
because the core InterBase documentation set is the same for each of these plat¬ 
forms, all file names in text and in examples are restricted to a base name with a 
maximum of eight characters, with a maximum extension length of three charac¬ 
ters. For example, the example database on all servers is referred to as 
employee.gdb. 

Generally, InterBase fully supports each platform's file-naming conventions, 
including the use of node and path names. InterBase, however, recognizes two 
categories of file specification in commands and statements that accept more 
than one file name. The first file specification is called the primary file specification. 
Subsequent file specifications are called secondary file specifications. Some com¬ 
mands and statements place restrictions on using node names with secondary 
file specifications. 
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In S5mtax, file specification is denoted as follows: 


" <filespec>" 


Primary File Specifications 

InterBase S5mtax always supports a full file specification, including optional 
node name and full path, for primary file specifications. For example, the S5mtax 
notation for CREATE DATABASE appears as follows: 

CREATE {DATABASE | SCHEMA} "<fllespec>" 

[USER "username" [PASSWORD "password"]] 

[PAGE_SIZE [=] int] 

[LENGTH [ = ] int [PAGE[S]]] 

[DEFAULT CHARACTER SET charset] 


In this S5mtax, the <filespec> that follows CREATE DATABASE supports a node 
name and path specification, including a platform-specific drive or volume spec¬ 
ification. 


Secondary File Specifications 

Eor InterBase S5mtax that supports multiple file specification, such as CREATE 
DATABASE, all file specifications after the first are secondary. Secondary file 
specifications generally carmot include a node name, but may specify a full path 
name. Eor example, the S5mtax notation for CREATE DATABASE appears as fol¬ 
lows: 

CREATE {DATABASE | SCHEMA} "<filespec>" 

[USER "username" [PASSWORD "password"]] 

[PAGE_SIZE [=] int] 

[LENGTH [ = ] int [PAGE[S]]] 

[DEFAULT CHARACTER SET charset] 

[<secondary_file>] 

<secondary_file> = FILE "<filespec>" [<fileinfo>] [<secondary_file>] 

<fileinfo> = LENGTH [=] int [PAGE[S]] | STARTING [AT [PAGE]] int 
[ <fileinfo>] 

In the secondary file specification, <filespec> does not support specification of a 
node name. 
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CHAPTER 1 

Introduction 


The InterBase Language Reference details the syntax and usage of SQL and 
D5mamic SQL (DSQL) statements for embedded applications programming, and 
for the InterBase interactive SQL utility, isql. It describes additional language 
and S5mtax specific to InterBase stored procedures and triggers. 


Who Should Use This Book 

The Language Reference assumes a general familiarity with SQL, data definition, 
data manipulation, and programming practice. It is a syntax and usage resource 
for: 


• Programmers writing embedded SQL and DSQL database applications. 

• Programmers writing directly to the InterBase applications program¬ 
ming interface (API), who need to know supported SQL S5mtax. 

• Database designers who create and maintain databases and tables with 

isql. 

• Users who perform queries and data manipulation operations through 

isql. 
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Topics Covered in This Book 


The following table lists the chapters in the Language Reference, and provides a 
brief description of them: 

Table 1 -1: Language Reference Chapters 

Chapter Description 

Chapter 1: Introduction Introduces the book, and describes its intended audience. 

Chapter 2: SQL Statement and Function Provides syntax and usage information for SQL and DSQL 
Reference statements. 

Chapter 3: Procedure and Trigger Describes syntax and usage information for stored procedure 

Language Reference and trigger language. 

Appendix A: Reserved Words Lists keywords, symbols, and punctuation, that have special 

meaning to InterBase. 

Appendix B: Error Codes and Messages Summarizes InterBase error messages and error codes. 
Appendix C: System Tables and Views Describes InterBase system tables and views that track meta¬ 
data. 

Appendix D: Character Sets and Collation Explains all about character sets and corresponding collation 
Qrders orders for a variety of environments and uses. 
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CHAPTER 2 

SQL Statement and 
Function Reference 


This chapter provides the S5mtax and usage for each InterBase SQL statement. It 
includes the following topics: 

• Statement List 

• Function List 

• Data Types 

• Error Handling 

• Using Statement and Function Definitions 


Statement List 


The following table lists the SQL statements described in this chapter: 


Table 2-1: SQL Statements 
ALTER DATABASE ALTER DOMAIN 

ALTER INDEX ALTER PROCEDURE 

ALTER TRIGGER BASED ON 


CLOSE 

CONNECT 

CREATE EXCEPTION 
CREATE PROCEDURE 
CREATE TRIGGER 
DECLARE CURSOR 
(BLOB) 

DECLARE STATEMENT 


CLOSE (BLOB) 
CREATE DATABASE 
CREATE GENERATOR 
CREATE SHADOW 
CREATE VIEW 
DECLARE EXTERNAL 
FUNCTION 
DECLARE TABLE 


ALTER EXCEPTION 
ALTER TABLE 
BEGIN DECLARE 
SECTION 
COMMIT 

CREATE DOMAIN 
CREATE INDEX 
CREATE TABLE 
DECLARE CURSOR 
DECLARE FILTER 

DELETE 
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Table 2-1: SQL Statements (Continued) 


DESCRIBE 
DROP DOMAIN 

DROP FILTER 

DROP SHADOW 

DROP VIEW 

EVENT WAIT 

EXECUTE PROCEDURE 

GRANT 

OPEN 

REVOKE 

SET DATABASE 

SET STATISTICS 

WHENEVER 


DISCONNECT 
DROP EXCEPTION 

DROP INDEX 

DROP TABLE 

END DECLARE SECTION 

EXECUTE 

FETCH 

INSERT 

OPEN (BLOB) 

ROLLBACK 
SET GENERATOR 
SET TRANSACTION 


DROP DATABASE 
DROP EXTERNAL 
FUNCTION 
DROP PROCEDURE 
DROP TRIGGER 
EVENT INIT 
EXECUTE IMMEDIATE 
FETCH (BLOB) 

INSERT CURSOR (BLOB) 

PREPARE 

SELECT 

SET NAMES 

UPDATE 


Function List 

The following table lists the SQL functions described in this chapter: 


Table 2-2: 

SQL Functions 


Function 

Type 

Purpose 

AVG() 

Aggregate 

Calculates the average of a set of values. 

CASTO 

Conversion 

Converts a column from one data type to another. 

COUNTO 

Aggregate 

Returns the number of rows that satisfy a query's search 
condition. 

GENJDQ 

Numeric 

Returns a system-generated value. 

MAX() 

Aggregate 

Retrieves the maximum value from a set of values. 

MINQ 

Aggregate 

Retrieves the minimum value from a set of values. 

SUMO 

Aggregate 

Totals the values in a set of numeric values. 

UPPERO 

Conversion 

Converts a string to all uppercase. 


Aggregate functions perform calculations over a series of values, such as the col¬ 
umns retrieved with a SELECT statement. 

Conversion functions transform data t5^es, either converting them from one 
t5^e to another, or by converting CHARACTER data t5^es to all uppercase. 
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The numeric function, GEN_ID(), produces a system-generated number that can 
be inserted into a column requiring a numeric data type. 


Data Types 

InterBase supports most SQL data types, but does not directly support the SQL 
DATE, TIME, and TIMESTAMP data t5q)es. In addition to standard SQL data 
t5q)es, InterBase also supports binary large object (BLQB) data t5q)es, and arrays 
of data types (except for BLQB data). 

The following table lists the data t5q)es available to SQL statements in InterBase: 


Table 2-3: Data Types Supported by InterBase 4.0 


Name 

Size 

Range/Precision 

Description 

BLOB 

Variable 

None. 

Binary large object. Stores large data, such 
as graphics, text, and digitized voice. Basic 
structural unit: segment. BLOB subtype 
describes BLOB contents. 

CHAR(n) 

n characters 

1 to 32,767 bytes. 
Character set character 
size determines the maxi¬ 
mum number of characters 
that can fit in 32K. 

Fixed length CHAR or text string type. 
Alternate keyword: CHARACTER. 

DATE 

64 bits 

1 Jan too to 11 Jan 5941. 

Also included time information. 

DECIMAL 
{precision, scaie) 

variable 

precision = 1 to 15. Speci¬ 
fies at least precision digits 
of precision to store. 
scaie = 1 to 15. Specifies 
number of decimal places 
for storage. Must be less 
than or equal to precision. 

Number with a decimal point scaie digits from 
the right. For example, DECIMAL(10, 3) 
holds numbers accurately in the following for¬ 
mat: 

ppppppp.sss 

DOUBLE 

PRECISION 

64 bits* 

1.7 X 10-308 to 1.7 X lO^os, 

Scientific: 15 digits of precision. 

FLOAT 

32 bits 

3.4 X 10-38 to 3.4 X 1038. 

Single precision: 7 digits of precision. 

INTEGER 

32 bits 

-2,147,483,648 to 
2,147,483,648. 

Signed long (longword). 
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Table 2-3: Data Types Supported by InterBase 4.0 (Continued) 


Name Size Range/Precision Description 


NUMERIC variable 
(precision, scaie) 


precision = 1 to 15. Speci¬ 
fies exactly precision dig¬ 
its of precision to store. 
scaie = 1 to 15. Specifies 
number of decimal places 
for storage. Must be less 
than or equal to precision. 


Number with a decimal point scaie digits from 
the right. For example, NUMERIC(10,3) 
holds numbers accurately in the following for¬ 
mat: 

ppppppp.sss 


SMALLINT 

VARCHAR(n) 


16 bits -32768 to 32767. Signed short (word). 


n characters 1 to 32765 bytes. Variable length CHAR or text string type. 

Character set character Alternate keywords: CHAR VARYING, 
size determines the maxi- CHARACTER VARYING, 
mum number of characters 
that can fit in 32K. 


+ Actuai size of DOUBLE is piatform dependent. Most piatforms support the 64 bit size. 


Error Handling 

Every time an executable SQL statement is executed, the SQLCODE variable is 
set to indicate its success or failure. SQLCODE is not generated for declarative 
statements that are not executed, such as DECLARE CURSOR, DECLARE 
TABLE, and DECLARE STATEMENT. 

The following table lists values that are returned to SQLCODE: 


Table 2-4: SQLCODE and Message Summary 


SQLCODE 

Message 

Meaning 

<0 

SQLERROR 

Error occurred. Statement did not execute. 

0 

SUCCESS 

Successful execution. 

-1-1-99 

SQLWARNING 

System warning or informational message. 

-1-100 

NOT FOUND 

No qualifying rows found, or end of current 
active set of rows reached. 

In isql when 

an error occurs, a 

n error message is displayed. 


In embedded applications, the programmer must provide error handling by 
checking the value of SQLCODE. 

To check SQLCODE, use one or a combination of the following approaches: 
• Test for SQLCODE values with the WHENEVER statement. 


12 


Language Reference 



ALTER DATABASE 


• Check SQLCODE directly. 

• Use the isc_print_sqlerror() routine to display specific error messages. 
For more information about error handling, see the Programmer's Guide. 


Using Statement and Function Definitions 


Each statement and function definition includes the following elements: 


Table 2-5: 
Element 
Irtie 

Definition 

Syntax 

Argument 

Description 

Examples 

See Also 


Statement and Function Format 
Description 
Statement name. 

The statement’s main purpose and availability. 

Diagram of the statement and its parameters. 

Parameters available for use with the statement. 

Information about using the statement. 

Examples of using the statement in a program and in isql. 

Where to find more information about the statement or others related to it. 


Most statements can be used in SQL, DSQL, and isql. In many cases, the S}mtax 
is nearly identical, except that embedded SQL statements must always be pre¬ 
ceded by the EXEC SQL keywords. EXEC SQL is omitted from s}mtax state¬ 
ments for clarity. 

In other cases there are small, but significant differences among SQL, DSQL, and 
isql syntax. In these cases, separate syntax statements appear rmder the state¬ 
ment heading. 


ALTER DATABASE 

Adds secondary files to the current database. Available in SQL, DSQL, and isql. 

Syntax alter {database I SCHEMA} 

ADD <add_clause>; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C-f-f, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


SQL Statement and Function Reference 


13 







ALTER DATABASE 


<add_clause> = 

FILE "<filespec>" [<fileinfo>] [<add_clause>] 

<fileinfo> = LENGTH [=] int [PAGE[S]] | STARTING [AT [PAGE]] int 
[<flleinfo>] 


Argument 

Description 

SCHEMA 

Alternative keyword for DATABASE. 

ADD FILE "<filespec>" Adds one or more secondary files to receive database pages 
after the primary file is filled. For a remote database, associate 
secondary files with the same node. 

LENGTH [=] int 
[PAGE[S]] 

Specifies the range of pages for a secondary file by providing the 
number of pages In each file. 

STARTING [AT 
[PAGE]] int 

Specifies a range of pages for a secondary file by providing the 
starting page number. 


Description ALTER DATABASE adds secondary files to an existing database. Secondary files 
are useful for controlling the growth and location of a database. They permit 
database files to be spread across storage devices, but must remain on the same 
node as the primary database file. 

A database can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 

ALTER DATABASE requires exclusive access to the database. 

Example The following isql statement adds secondary files to an existing database: 

ALTER DATABASE 

ADD FILE "employee.gdl" 

STARTING AT PAGE lOOOI 
LENGTH 10000 
ADD FILE "employee.gd2" 

LENGTH 10000; 

See Also CREATE DATABASE, DROP DATABASE 

For more information about multi-file databases, see the Data Definition Guide. 

For more information about exclusive database access, see the Windows Client 
User's Guide. 
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ALTER DOMAIN 


ALTER DOMAIN 

Changes a domain definition. Available in SQL, DSQL, and isql. 

Syntax alter domain name { 

[SET DEEAULT {literal I NULL | USER}] 

I [DROP DEFAULT] 

I [ADD [CONSTRAINT] CHECK (<dom_search_condltion>)] 

I [DROP CONSTRAINT] 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<dom_search_condition> = { 

VALUE <operator> <val> 

I VALUE [NOT] BETWEEN <val> AND <val> 

I VALUE [NOT] LIKE <val> [ESCAPE <val>] 

I VALUE [NOT] IN (<val> [, <val> ...]) 

I VALUE IS [NOT] NULL 
I VALUE [NOT] CONTAINING <val> 

I VALUE [NOT] STARTING [WITH] <val> 

I (<dom_search_condition>) 

I NOT <dom_search_condition> 

I <dom_search_condition> OR <dom_search_conditlon> 

I <dom_search_condition> AND <dom_search_condition> 


<operator> = 




Argument 


Description 


name 

SET DEFAULT 


DROP DEFAULT 


Name of an existing domain. 

Specifies a default column value that is entered when no 
other entry is made. Values: 

• //fera/—Inserts a specified string, numeric value, or date 
value. 

• NULL—Enters a NULL value. 

• USER—Enters the user name of the current user. Col¬ 
umn must be of compatible text type to use the default. 

Defaults set at column level override defaults set at the 
domain level. 

Drops existing default. 
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ALTER EXCEPTION 


Argument Description 

ADD [CONSTRAINT] Adds a CHECK constraint to the domain definition. A 
CHECK domain definition can include only one CHECK constraint. 

<dom_search_condition> 

DROP CONSTRAINT Drops CHECK constraint from the domain definition. 

Description ALTER DOMAIN changes any aspect of an existing domain except its data t5rpe 
and NOT NULL setting. Changes made to a domain definition affect all column 
definitions based on the domain that have not been overridden at the table level. 

Note To change a data t5rpe or NOT NULL setting of a domain, drop the domain 
and recreate it with the desired combination of features. 

A domain can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 


Example The following isql statements create a domain that must have a value > 1,000, 
then alter it by setting a default of 9,999: 

CREATE DOMAIN CUSTNO 
AS INTEGER 

CHECK (VALUE > 1000); 

ALTER DOMAIN CUSTNO SET DEFAULT 9999; 


See Also CREATE DOMAIN, CREATE TABLE, DROP DOMAIN 

Eor a complete discussion of creating domains, and using them to create column 
definitions, see the Data Definition Guide. 


ALTER EXCEPTION 

Changes the message associated with an existing exception. Available in DSQL 
and isql. 

Syntax alter exception name "<message>" 


Argument 

Description 

name 

"<message>" 

Name of an existing exception message. 

Quoted string containing ASCII values. 


Description ALTER EXCEPTION changes the text of an exception error message. 

Am exception can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 
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ALTER INDEX 


Example This isql statement alters the message of an exception: 

ALTER EXCEPTION CUSTOMER_CHECK "Hold shipment for customer 
remittance."; 

See Also ALTER PROCEDURE, ALTER TRIGGER, GREATE EXGEPTION, GREATE 
PROGEDURE, GREATE TRIGGER, DROP EXGEPTION 

For more information on creating, raising, and handling exceptions, see the Data 
Definition Guide. 


ALTER INDEX 


Activates or deactivates an index. Available in SQL, DSQL, and isql. 

Syntax alter index name {ACTIVE | INACTIVE}; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument Description 

name Name of an existing index. 

ACTIVE Changes an INACTIVE index to an ACTIVE one. 

INACTIVE Changes an ACTIVE index to an INACTIVE one. 

Description ALTER INDEX makes an inactive index available for use, or disables the use of 
an active index. Deactivating and reactivating an index is useful when changes 
in the distribution of indexed data cause the index to become imbalanced. 

Before inserting or updating a large number of rows, deactivate a table's indexes 
to avoid altering the index incrementally. When finished, reactivate the index. 
Reactivating a deactivated index rebuilds and rebalances an index. 

If an index is in use, ALTER INDEX does not take effect until the index is no 
longer in use. 

ALTER INDEX fails and returns an error if the index is defined for a UNIQUE, 
PRIMARY KEY, or FQREIGN KEY constraint. To alter such an index, use DRQP 
INDEX to delete the index, then recreate it with CREATE INDEX. 

Am index can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 
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ALTER PROCEDURE 


Note To add or drop index columns or keys, use DROP INDEX to delete the 
index, then recreate it with CREATE INDEX. 


Example The following isql statements deactivate and reactivate an index to rebuild it: 

ALTER INDEX BUDGETX INACTIVE; 

ALTER INDEX BUDGETX ACTIVE; 

See Also ALTER TABLE, CREATE INDEX, DROP INDEX, SET STATISTICS 


ALTER PROCEDURE 

Changes the definition of an existing stored procedure. Available in DSQL and 

isql. 

Syntax alter procedure name 

Iiparam <datatype> [, param <datatype> ...])] 

[RETURNS iparam <datatype> [, param <datatype> ...])] 

AS <procedure_body> [terminator] 


Argument 

Description 

name 

Name of an existing procedure. 

param <datatype> 

Input parameters used by the procedure. Legal data types are 
listed under CREATE PROCEDURE. 

RETURNS 
param <datatype> 

Output parameters used by the procedure. Legal data types are 
listed under CREATE PROCEDURE. 

<procedure_body> 

The procedure body. Includes: 

• Local variable declarations 

• A block of statements in procedure and trigger language 

See CREATE PROCEDURE for a complete description. 

terminator 

Terminator defined by the isql SET TERM command to signify 
the end of the procedure body. Required by isql. 


Description ALTER PROCEDURE changes an existing stored procedure without affecting its 
dependencies. It can modify a procedure's input parameters, output parameters, 
and body. 

The complete procedure header and body must be included in the ALTER 
PROCEDURE statement. The S5mtax is exactly the same as CREATE 
PROCEDURE, except CREATE is replaced by ALTER. 

Caution Be careful about changing the type, number, and order of input and output 
parameters to a procedure, since existing application code may assume the 
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ALTER TABLE 


procedure has its original format. 

A procedure can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 

Procedures in use are not altered until they are no longer in use. 

ALTER PROCEDURE changes take effect when they are committed. Changes 
are then reflected in all applications that use the procedure without recompiling 
or relinking. 

Example The following isql statements alter the GET_EMP_PROJ procedure, changing 
the return parameter to have a data type of VARCHAR( 20 ): 

SET TERM !! ; 

ALTER PROCEDURE GET_EMP_PROJ (EMP_NO SMALLINT) 

RETURNS (PROJ_ID VARCHAR(20)) AS 
BEGIN 

FOR SELECT PROJ_ID 
FROM EMPLOYEE_PROJECT 
WHERE EMP_NO = :emp_no 
INTO :proj_id 
DO 

SUSPEND; 

END ! ! 

SET TERM ; !! 

See Also CREATE PROCEDURE, DROP PROCEDURE, EXECUTE PROCEDURE 

For more information on creating and using procedures, see the Data Definition 
Guide. 

For a complete description of the statements in procedure and trigger language, 
see Chapter 3 : "Procedure and Trigger Language Reference." 


ALTER TABLE 

Changes a table by adding or dropping columns or integrity constraints. Avail¬ 
able in SQL, DSQL, and isql. 

Syntax ALTER TABLE table <operation> [, <operation> ...]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 
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ALTER TABLE 


<operation> = {ADD <col_def> \ ADD <table_constraint> | DROP col 
I DROP CONSTRAINT constraint] 

<col_def> = col {<datatype> \ [COMPUTED [BY] (<expr>) \ domain] 
[DEFAULT {literal \ NULL | USER}] 

[NOT NULL] [<col_constraint>] 

[COLLATE collation] 

Note The COLLATE clause cannot be specified for BLOB columns. 

<col_constraint> = [CONSTRAINT constraint] <constraint_def> 

[<col_constraint>] 

<constraint_def> = {PRIMARY KEY | UNIQUE 
I CHECK (<search_condition>) 

I REFERENCES other_table [{other_col [, other_col ...])]} 
<datatype> = { 

{SMALLINT I INTEGER | FLOAT | DOUBLE PRECISION} [<array_dim>] 
I {DECIMAL I NUMERIC} [{precision [, scale])] [<array_dlin>] 

I DATE [<array_dim>] 

I {CHAR I CHARACTER | CHARACTER VARYING | VARCHAR} 

[ (1. . .32767) ] [<array_dim>] [CHARACTER SET charname] 

I [NCHAR I NATIONAL CHARACTER | NATIONAL CHAR} 

[VARYING] [ (1. . .32767) ] l<array_dim>] 

I BLOB [SUB_TYPE { int | subtype_name]] [SEGMENT SIZE n] 
[CHARACTER SET charname] 

I BLOB [(seglen [, subtype])] 


<array_dim> = [x:y [, x:y ...]] 

Note Outermost brackets, in bold, must be included when declaring arrays. 

<table_constraint> = [CONSTRAINT constraint] <tconstraint_opt> 
[<table_constraint>] 

<tconstraint_opt> = { 

{PRIMARY KEY | UNIQUE} (col [, col ...]) 

I FOREIGN KEY (col [, col ...]) REFERENCES Other_table 
I CHECK {<search_condition>) 

] 

Note For the full S5mtax of <search_condition>, see CREATE TABLE. 


Argument Description 

table Name of an existing tabie to modify. 

<operation> Action to perform on the tabie. Vaiid options are: 

• ADD a new column or table constraint to a tabie. 

• DROP an existing coiumn or constraint from a table. 
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ALTER TABLE 


Argument 

Description 

<col_def> 

Description of a new coiumn to add. Must inciude a coiumn name 
and data type. Can include default values, column constraints, 
and a specific collation order. 

<table_constraint> 

Description of a new table constraint to add. Only one table con¬ 
straint can be added to a table. 

col 

Name of column to add or drop. Column name must be unique 
within the table. 

<constraint> 

Name of constraint to add or drop. Constraint name must be 
unique within the table. 

COLLATE collation 

Adds a collation order to the specified table. 

<datatype> 

Data type of column to add. 

domain 

Name of a domain upon which a column definition should be 
based. 

COMPUTED [BY] 

Specifies a column calculated from <expr> and which is not 

<expr> 

therefore allocated storage space in the database. <expr> can 
be any arithmetic expression valid for the data types in the 
expression. Other columns referenced in <expr> must exist 
before they can be used. BLOB columns cannot be referenced. 
<expr> must return a single value, and cannot return an array. 

NOT NULL 

Specifies that a column cannot contain a NULL value. If a table 
already has rows, a new column cannot be NOT NULL. NOT 
NULL is only a column attribute. 

DEFAULT 

Specifies a default column value that is entered when no other 
entry is made. Values: 

• literal: Inserts a specified string, numeric value, or date value. 

• NULL: Enters a NULL value. 

• USER: Enters the user name of the current user. Column 
must be of compatible text type to use the default. 

• Defaults set at column level override defaults set at the 
domain level. 

<constraint_def> 

Column constraint definition. 

CONSTRAINT 

Adds a named constraint to a column. 

DROP CONSTRAINT 

Drops the specified table constraint. 


Description ALTER TABLE enables the structure of an existing table to be modified. A single 
ALTER TABLE can perform multiple adds and drops. 

Creating PRIMARY KEY and EOREIGN KEY constraints requires exclusive 
access to the database. 
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ALTER TABLE 


Caution 

Examples 

Note 


See Also 


Naming column constraints is optional. If a name is not specified, InterBase 
assigns a system-generated name. Assigning a descriptive name can make a con¬ 
straint easier to find for changing or dropping, and easier to find when its name 
appears in a constraint violation error message. 

A table can be altered by its creator, the SYSDBA user, and any users with oper¬ 
ating system root privileges. 

ALTER TABLE fails if current data in a table violates a PRIMARY KEY or 
UNIQUE constraint definition added to the table. It also fails if a column to be 
dropped is: 

• Part of a UNIQUE, PRIMARY, or PQREIGN KEY constraint, or is used in 
a CHECK constraint. 

• Used in the value expression of a computed column. 

Drop the constraint or computed column before dropping the table column. 
PRIMARY KEY and UNIQUE constraints cannot be dropped if referenced by 
EQREIGN KEY constraints. In these cases, drop the EQREIGN KEY constraint 
before dropping the PRIMARY KEY or UNIQUE key it references. 

When altering a column based on a domain, an additional CHECK constraint 
can be supplied for the colmnn. Changes to tables that contain CHECK con¬ 
straints with subqueries may cause constraint violations. 

When a column is altered or dropped any data stored in it is lost. 

The following isql statement adds a column to a table and drops a column: 

ALTER TABLE COUNTRY 

ADD CAPITAL VARCHAR(25), 

DROP CURRENCY; 

This statement results in the loss of any data in the dropped column. 

The next isql statement adds two columns to a table and defines a UNIQUE con¬ 
straint on one of them: 

ALTER TABLE COUNTRY 

ADD CAPITAL VARCHAR(25) NOT NULL UNIQUE, 

ADD LARGEST_CITY VARCHAR(25) NOT NULL; 

ALTER DQMAIN, CREATE DQMAIN, CREATE TABLE 

Eor more information about preserving data in columns before altering them, 
see the Programmer's Guide. 
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ALTER TRIGGER 

Changes an existing trigger. Available in DSQL and isql. 

Syntax alter trigger name 

[ACTIVE I INACTIVE] 

[{BEFORE I AETER} {DELETE | INSERT | UPDATE}] 
[POSITION number] 

[AS <trigger_body>] [terminator] 


Argument 

Description 

name 

Name of an existing trigger. 

ACTIVE 

Specifies that a trigger action takes effect when fired 
(default). 

INACTIVE 

Specifies that a trigger action does not take effect. 

BEFORE 

Specifies the trigger fires before the associated operation 
takes place. 

AFTER 

Specifies the trigger fires after the associated operation takes 
place. 

DELETE 1 INSERT 

1 UPDATE 

Specifies the table operation that causes the trigger to fire. 

POSITION number 

Specifies order of firing for triggers before the same action or 
after the same action, number must be an integer between 0 
and 32,767, inclusive. Lower-number triggers fire first. 

Triggers for a table need not be consecutive. Triggers on the 
same action with the same position number will fire in ran¬ 
dom order. 

<trigger_bocly> 

Body of the trigger, a block of statements in procedure and 
trigger language. See CREATE TRIGGER for a complete 
description. 

terminator 

Terminator defined by the isql SET TERM command to sig¬ 
nify the end of the trigger body. Not needed when altering 
only the trigger header. 


Description ALTER TRIGGER changes the definition of an existing trigger. If any of the argu¬ 
ments to ALTER TRIGGER are omitted, then they default to their current values, 
that is the value specified by GREATE TRIGGER, or the last ALTER TRIGGER. 

ALTER TRIGGER can change: 
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AVGO 


• Header information only, including the trigger activation status, when it 
performs its actions, the event that fires the trigger, and the order in 
which the trigger fires compared to other triggers. 

• Body information only, the trigger statements that follow the AS clause. 

• Header and trigger body information. In this case, the new trigger defini¬ 
tion replaces the old trigger definition. 

A trigger can be altered by its creator, the SYSDBA user, and any users with 
operating system root privileges. 

Note To alter a trigger defined automatically by a CHECK constraint on a table, 
use ALTER TABLE to change the constraint definition. 

Examples The following isql statement modifies the trigger, SET_CUST_NO, to be inac¬ 
tive: 

ALTER TRIGGER SET_CUST_NO INACTIVE; 

The next isql statement modifies the trigger, SET_CUST_NO, to insert a row into 
the table, NEW_CUSTOMERS, for each new customer. 

SET TERM !! ; 

ALTER TRIGGER SET_CUST_NO FOR CUSTOMER 
BEFORE INSERT AS 
BEGIN 

NEW.CUST_NO = GEN_ID(CUST_NO_GEN, 1); 

INSERT INTO NEW_CUSTOMERS(NEW.CUST_NO, TODAY) 

END ! ! 

SET TERM ; ! ! 

See Also CREATE TRIGGER, DROP TRIGGER 

Eor a complete description of the statements in procedure and trigger language, 
see Ghapter 3: "Procedure and Trigger Language Reference." 

Eor more information about triggers, see the Data Definition Guide. 


AVGO 

Galculates the average of numeric values in a specified column or expression. 
Available in SQL, DSQL, and isql. 

Syntax AVG ([all] <val> \ distinct <val>) 
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BASED ON 


Description 

Exampies 

See Aiso 

BASED ON 

Syntax 


Argument Description 

ALL Returns the average of all values. 

DISTINCT Eliminates duplicate values before calculating the average. 

<val> A column or expression that evaluates to a numeric data type. 


AVG() is an aggregate function that returns the average of the values in a speci¬ 
fied column or expression. Only numeric data t 5 rpes are allowed as input to 
AVG(). 

If a field value involved in a calculation is NULL or unknown, it is automatically 
excluded from the calculation. Automatic exclusion prevents averages from 
being skewed by meaningless data. 

AVG() computes its value over a range of selected rows. If the number of rows 
returned by a SELECT is zero, AVG() returns a NULL value. 

The following embedded SQL statement returns the average of all rows in a 
table: 

EXEC SQL 

SELECT AVG (BUDGET) FROM DEPARTMENT INTO :avg_budget; 

The next embedded SQL statement demonstrates the use of SUM(), AVG(), 
MIN(), and MAX() over a subset of rows in a table: 

EXEC SQL 

SELECT SUM (BUDGET), AVG (BUDGET), MIN (BUDGET), MAX (BUDGET) 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :head_dept 

INTO :tot_budget, :avg_budget, :min_budget, :max_budget; 

CQUNTO, MAX(), MIN(), SUM() 


Declares a host-language variable based on a column. Available in SQL. 

BASED [ON] [dihandle.]table.col[.SEGMENT] variable; 
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BASED ON 


Description 


Note 


Exampies 


See Aiso 


Argument 

Description 

dbhandle. 

Handle for the database in which a table resides in a multi¬ 
database program, dbhandle must be previously declared in a 
SET DATABASE statement. 

table, col 

Name of table and name of column on which the variable is 
based. 

.SEGMENT 

Bases the local variable size on the segment length of the BLOB 
column during BLOB FETCH operations. Use only when 
table.col refers to a column of BLOB data type. 

variable 

Name of the host-language variable that inherits the characteris¬ 
tics of a database column. 


BASED ON is a preprocessor directive that creates a host-language variable 
based on a column definition. The host variable inherits the attributes described 
for the column and any characteristics that make the variable t5^e consistent 
with the programming language in use. For example, in C, BASED ON adds one 
byte to CHAR and VARCHAR variables to accommodate the NULL character 
terminator. 

Use BASED ON in a program's variable declaration section. 

BASED ON does not require the EXEC SQL keywords. 

To declare a host-language variable large enough to hold a BLOB segment 
during FETCH operations, use the SEGMENT option of the BASED ON clause. 
The variable's size is derived from the segment length of a BLOB column. If the 
segment length for the BLOB column is changed in the database, recompile the 
program to adjust the size of host variables created with BASED ON. 

The following embedded statements declare a host variable based on a column: 

EXEC SQL 

BEGIN DECLARE SECTION 

BASED_ON EMPLOYEE.SALARY salary; 

EXEC SQL 

END DECLARE SECTION; 

BEGIN DEGLARE SEGTION, GREATE TABLE, END DEGLARE SEGTION 
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BEGIN DECLARE SECTION 


BEGIN DECLARE SECTION 



Identifies the start of a host-language variable declaration section. Available in 
SQL. 

Syntax 

BEGIN DECLARE SECTION; 

Description 

BEGIN DECLARE SECTION is used in embedded SQL applications to identify 
the start of host-language variable declarations for variables that will be used in 
subsequent SQL statements. BEGIN DECLARE SECTION is also a preprocessor 
directive that instructs gpre to declare SQLCODE automatically for the applica¬ 
tions programmer. 

Important 

BEGIN DECLARE SECTION must always appear within a module's glo¬ 
bal variable declaration section. 

Exampie 

The following embedded SQL statements declare a section and a host-language 
variable: 

EXEC SQL 

BEGIN DECLARE SECTION; 

BASED ON EMPLOYEE.SALARY salary; 

EXEC SQL 

END DECLARE SECTION; 

See Aiso 

BASED ON, END DECLARE SECTION 


CASIO 



Converts a column from one data t5q)e to another. Available in SQL, DSQL, and 

isql. 

Syntax 

CAST {<val> AS <datatype>) 

Argument Description 

<val> A column, constant, or expression. In SQL, <val> can also be a 

host-language variable, function, or DDF. 

<datatype> Data type to which to convert. 

Description 

CAST() allows mixing of numerics and characters in a single expression by con¬ 
verting <val> to a specified data t}rpe. 
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CLOSE 


Example 

See Also 

CLOSE 

Syntax 

Description 


Normally, only similar data types can be compared in search conditions. CAST() 
can be used in search conditions to translate one data \y'pe into another for com¬ 
parison purposes. 


Data t5rpes can be converted as shown in the following table: 

Table 2-6: Compatible Data Types for CAST() 

From Data Type Class 

To Data Type Class 

numeric 

character, varying character, date 

character, varying character 

numeric, date 

date 

character, varying character, date 

BLOB, arrays 

- 


An error results if a given data t5^e cannot be converted into the data type spec¬ 
ified in CAST(). 

In the following WHERE clause, CAST() is used to translate a CHARACTER 
data t5^e, INTERVIEW_DATE, to a DATE data t5^e to compare against a DATE 
data t5^e, HIRE_DATE: 

WHERE HIRE_DATE = CAST (INTERVIEW_DATE AS DATE); 

UPPERO 


Closes an open cursor. Available in SQL. 

CLOSE cursor; 


Argument 

Description 

cursor 

Name of an open cursor. 


CLOSE terminates the specified cursor, releasing the rows in its active set and 
any associated system resources. A cursor is a one-way pointer into the ordered 
set of rows retrieved by the select expression in the DECLARE CURSOR state¬ 
ment. A cursor enables sequential access to retrieved rows in turn and update in 
place. 
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CLOSE (BLOB) 


There are four related cursor statements: 


Stage Statement 

Purpose 

1 

DECLARE 

CURSOR 

Declares the cursor. The SELECT statement determines rows 
retrieved for the cursor. 

2 

OPEN 

Retrieves the rows specified for retrieval with DECLARE 
CURSOR. The resulting rows become the cursor’s active set. 

3 

FETCH 

Retrieves the current row from the active set, starting with the 
first row. Subsequent FETCH statements advance the cursor 
through the set. 

4 

CLOSE 

Cioses the cursor and releases system resources. 


FETCH statements cannot be issued against a closed cursor. Until a cursor is 
closed and reopened, InterBase does not reevaluate values passed to the search 
conditions. Another user can commit changes to the database while a cursor is 
open, making the active set different the next time that cursor is reopened. 

Note In addition to CLOSE, COMMIT and ROLLBACK automatically close all 
cursors in a transaction. 

Example The following embedded SQL statement closes a cursor: 

EXEC SQL 

CLOSE BC; 

See Also CLOSE (BLOB), COMMIT, DECLARE CURSOR, LETCH, OPEN, ROLLBACK 


CLOSE (BLOB) 

Terminates a specified BLOB cursor and releases associated system resources. 
Available in SQL. 

Syntax close blob_cursor; 


Argument 

Description 

blob_cursor 

Name of an open BLOB cursor. 

Description CLQSE doses a 

n opened read or insert BLQB cursor. Generally a BLQB cursor 


should only be closed after: 

• Letching all the BLQB segments for BLQB READ operations. 

• Inserting all the segments for BLQB INSERT operations. 
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COMMIT 


Example The following embedded SQL statement closes a BLOB cursor: 

EXEC SQL 

CLOSE BC; 

See Also DECLARE CURSOR (BLOB), EETCH (BLOB), INSERT CURSOR (BLOB), OPEN 

(BLOB) 


COMMIT 

Makes a transaction's changes to the database permanent, and ends the transac¬ 
tion. Available in SQL, DSQL, and isql. 

Syntax commit [work] [transaction name] [RELEASE] [RETAIN [SNAPSHOT]]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument Description 

WORK An optional word used for compatibility with other relational data¬ 

bases that require it. 

TRANSACTION Commits transaction name to database. Without this option, 
name COMMIT affects the default transaction. 

RELEASE Available for compatibility with earlier versions of InterBase. 

RETAIN [SNAPSHOT] Commits changes and retains current transaction context. 


Description COMMIT is used to end a transaction and: 

• Write all updates to the database. 

• Make the transaction's changes visible to subsequent SNAPSHOT trans¬ 
actions or READ COMMITTED transactions. 

• Close open cursors, unless the RETAIN argument is used. 

A transaction ending with COMMIT is considered a successful termination. 
Always use COMMIT or ROLLBACK to end the default transaction. 

Tip After read-only transactions, which make no database changes, use 

COMMIT rather than ROLLBACK. The effect is the same, but the perfor¬ 
mance of subsequent transactions is better and the system resources used 
by them are reduced. 
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CONNECT 


Important The RELEASE argument is only available for compatibility with previous 
versions of InterBase. To detach from a database use DISCONNECT. 

Examples The following isql statement makes permanent the changes to the database 
made by the default transaction: 

COMMIT; 

The next embedded SQL statement commits a named transaction: 

EXEC SQL 

COMMIT TRl; 

The following embedded SQL statement uses CQMMIT RETAIN to commit 
changes while maintaining the current transaction context: 

EXEC SQL 

COMMIT RETAIN; 

See Also DISCQNNECT, RQLLBACK 

Eor more information about handling transactions, see the Programmer's Guide. 


CONNECT 


Attaches to one or more databases. Available in SQL. A subset of CQNNECT 
options is available in isql. 

Syntax SQL form: 

CONNECT [TO] {{ALL | DEFAULT} [<config_opts>] \ <db_specs>}; 

<db_specs> = { {" <filespec>" \ -.variable} AS dbhandle | dbhandle] 
[<config_opts>} [, <db_specs>} 

<config_opts> = USER {"username" I -.variable) 

I PASSWORD {"password" \ -.variable] 

I CACHE int [BUFFERS] [<config_opts>] 

isql form: 

CONNECT ["]<fllespec>["] [USER "username"[PASSWORD "password"]] 


Argument Description 

{ALL I DEFAULT} Connects to all databases specified with SET DATABASE. Any 
options specified with CONNECT TO ALL affect ail databases. 
"<filespec>" Database file name. Can include path specification and node. 
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CONNECT 


Description 


Argument 

Description 

dbhandle 

Database handle declared In a previous SET DATABASE state¬ 
ment. 

-.variable 

Host-language variable specifying a database, user name, or 
password. 

AS 

Attaches to a database and assigns a previously declared han¬ 
dle to it. 

USER "username" 

String or host-language variable that specifies a user name for 

1 -.variable 

use when attaching to the database. The server checks the user 
name against the security database. User names are case insen¬ 
sitive on the server. 

PASSWORD 

String or host-language variable, up to 8 characters in size, that 

"password' 

specifies password for use when attaching to the database. The 

1 -.variable 

server checks the user name and password against the security 
database. Case sensitivity is retained for the comparison. 

CACHE int 

Sets the number of cache buffers for a database, which deter¬ 

[BUFFERS] 

mines the number of database pages a program can use at the 
same time. Values for int. 

• Default: 75. 

• Minimum value: 45. 

• Maximum value: System-dependent. 

Do not use "<filespec>" form of database name with cache 
assignments. 


The CONNECT statement: 


• Initializes database data structures. 

• Determines if the database is on the originating node (a local database) or 
on another node (a remote database). Databases used by PC clients are 
always located on remote servers. An error message occurs if InterBase 
cannot locate the database. 

• Optionally specifies a user name and password for use when attaching to 
the database. PC clients must always send a valid user name and pass¬ 
word. Passwords are restricted to 8 characters in length. 

• Attaches to the database and verifies the header page. The database file 
must contain a valid database, and the on-disk structure (ODS) version 
number of the database must be the one recognized by the installed ver¬ 
sion of InterBase on the server, or InterBase returns an error. 

• Optionally establishes a database handle declared in a SET DATABASE 
statement. 

• Specifies a cache buffer for the process attaching to a database. 
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CONNECT 


In SQL programs before a database can be opened with CONNECT, it must be 
declared with the SET DATABASE statement, isql does not use SET DATABASE. 

In SQL programs while the same CONNECT statement can open more than one 
database, use separate statements to keep code easy to read. 

When CONNECT attaches to a database, it uses the default character set 
(NONE), or one specified in a previous SET NAMES statement. 

In SQL programs the CACHE option changes the database cache size coxmt (the 
total number of available buffers) from the default of 75. This option can be used 
to: 


• Set a new default size for all databases listed in the CONNECT statement 
that do not already have a specific cache size. 

• Specify a cache for a program that uses a single database. 

• Change the cache for one database without changing the default for all 
databases used by the program. 

The size of the cache persists as long as the attachment is active. If a database is 
already attached through a multi-client server, an increase in cache size due to a 
new attachment persists until all the attachments end. A decrease in cache size 
does not affect databases that are already attached through a server. 

A subset of CONNECT features is available in isql: database file name, USER, 
and PASSWORD, isql can only be cormected to one database at a time. Each 
time CONNECT is used to attach to a database, previous attachments are dis- 
cormected. 

Examples The following statement opens a database for use in isql. It uses all the 
CONNECT options available to isql: 

CONNECT "employee.gdb" USER "ACCT_REC" PASSWORD "peanuts"; 

The next statement, from an embedded application, attaches to a database file 
stored in the host-language variable and assigns a previously declared database 
handle to it: 

EXEC SQL 

SET DATABASE DBl = "employee.gdb"; 

EXEC SQL 

CONNECT :db_file AS DBl; 

The following embedded SQL statement attaches to employee.gdb and allocates 
150 cache buffers: 

EXEC SQL 

CONNECT "accounts.gdb" CACHE 150; 
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The next embedded SQL statement connects the user to all databases specified 
with previous SET DATABASE statements: 

EXEC SQL 

CONNECT ALL USER "ACCT_REC" PASSWORD "peanuts" 

CACHE 50; 

The following embedded SQL statement attaches to the database, employee.gdb, 
with 80 buffers and database employeel.gdb with the default of 75 buffers: 

EXEC SQL 

CONNECT "employee.gdb" CACHE 80, "employee2.gdb"; 

The next embedded SQL statement attaches to all databases and allocates 50 
buffers: 

EXEC SQL 

CONNECT ALL CACHE 50; 

The following embedded SQL statement connects to EMPl and EMP2, setting 
the number of buffers for each to 80: 

EXEC SQL 

CONNECT EMPl CACHE 80, EMP2 CACHE 80; 

The next embedded SQL statement connects to two databases identified by vari¬ 
able names, setting different user names and passwords for each: 

EXEC SQL 
CONNECT 

:orderdb AS DBl USER "ACCT_REC" PASSWORD "peanuts", 

:salesdb AS DB2 USER "ACCT_PAY" PASSWORD "payout"; 

See Also DISCQNNECT, SET DATABASE, SET NAMES 

Eor more information about cache buffers, see the Data Definition Guide. 

Eor more information about database security, see the Windows Client User's 
Guide. 

Eor more information about isql, see Getting Started. 


COUNTO 


Calculates the number of rows that satisfy a query's search condition. Available 
in SQL, DSQL, and isql. 

Syntax count ( * | [all] <val> \ distinct <val>) 
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Argument Description 

* Retrieves the number of rows in a specified table, including 

NULL values. 

ALL Counts all non-NULL values in a column. 

DISTINCT Returns the number of unique, non-NULL values for the column. 

<val> A column or expression. 

Description 

COUNT() is an aggregate function that returns the number of rows that satisfy a 
query's search condition. It may be used in views and joins as well as tables. 

Exampie 

The following embedded SQL statement returns the number of unique currency 
values it encoxmters in the COUNTRY table: 

EXEC SQL 

SELECT COUNT (DISTINCT CURRENCY) INTO : cnt FROM COUNTRY; 

See Aiso 

AVG(), MAX{), MIN{), SUM() 


CREATE DATABASE 



Creates a new database. Available in SQL, DSQL, and isql. 

Syntax 

CREATE {DATABASE | SCHEMA} "<filespec>" 

[USER "username" [PASSWORD "password"]] 

[PAGE_SIZE [=] int] 

[LENGTH [=] Int [PAGE[S]]] 

[DEFAULT CHARACTER SET charset] 

[<secondary_fIle >]; 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C-n-, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<secondary_file> = FILE " <fllespec>" [<filelnfo>] [<secondary_flle>] 

<fileinfo> = LENGTH [=] int [PAGE[S]] | STARTING [AT [PAGE]] int 
[<fileinfo>] 
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CREATE DATABASE 


Description 


Argument 

Description 

"<filespec>" 

A new database file specification. File naming conventions are 
platform-specific. 

USER "username" 

If provided, the user name is checked against valid user name 
and password combinations in the security database on the 
server where the database will reside. Windows client applica¬ 
tions must provide a user name on attachment to a server. Any 
client application attaching to a database on NT or NetWare must 
provide a user name on attachment. 

PASSWORD 

"password' 

Up to 8 characters. The password is checked against valid user 
name and password combinations in the security database on 
the server where the database will reside. Windows client appli¬ 
cations must provide a user name and password on attachment 
to a server. Any client application attaching to a database on NT 
or NetWare must provide a password on attachment. 

PAGE_SIZE [=] int 

Size, in bytes, for database pages, int can be 1024 (default), 
2048, 4096, or 8192. 

DEFAULT 
CHARACTER SET 
charset 

Sets default character set for a database, charset \s the name of 
a character set. If omitted, character set defaults to NONE. 

FILE "<filespec>" 

Names one or more secondary files to hold database pages after 
the primary file is filled. For databases created on remote serv¬ 
ers, secondary file specifications cannot include a node name. 

STARTING [AT 
[PAGE]] int 

Specifies the starting page number for a secondary file. 

LENGTH [=] 
/nf[PAGE[S]] 

Specifies the length of a primary or secondary database file. Use 
for primary file only if defining a secondary file in the same state¬ 
ment. 


CREATE DATABASE creates a database and establishes the following character¬ 
istics for it: 

• The name of the primary file that identifies the database for users. By 
default, databases are contained in single files. 

• The name of any secondary files in which the database is stored. A data¬ 
base can reside in more than one disk file if additional file names are 
specified as secondary files. If a database is created on a remote server, 
secondary file specifications carmot include a node name. 

• The size of database pages. Increasing page size can improve perfor¬ 
mance for the following reasons: 
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CREATE DATABASE 


• Indexes work faster because the depth of the index is kept to a mini¬ 
mum. 

• Keeping large rows on a single page is more efficient. 

• BLOB data is stored and retrieved more efficiently when it fits on a 
single page. 

If most transactions involve only a few rows of data, a smaller page size 
may be appropriate, since less data needs to be passed back and forth 
and less memory is used by the disk cache. 

• The number of pages in each database file. 

• The character set used by the database. For a list of the character sets rec¬ 
ognized by InterBase, see Appendix D: "Character Sets and Collation 
Orders." 

Choice of DEFAULT CHARACTER SET limits possible collation orders 
to a subset of all available collation orders. Given a specific character set, 
a specific collation order can be specified when data is selected, inserted, 
or updated in a column. 

If you do not specify a default character set, the character set defaults to 
NONE. Using character set NONE means that there is no character set 
assumption for colnmns; data is stored and retrieved just as you origi¬ 
nally entered it. You can load any character set into a column defined 
with NONE, but you cannot load that same data into another column 
that has been defined with a different character set. In that case, no trans¬ 
literation is performed between the source and destination character sets, 
and transliteration errors may occur during assignment. 

• System tables that describe the structure of the database. 

After creating the database, a user may define its tables, views, indexes, and sys¬ 
tem views. 

Important In DSQL, CREATE DATABASE can only be executed with EXECUTE 

IMMEDIATE. The database handle and transaction name, if present, must 
be initialized to zero prior to use. 

Examples The following isql statement creates a database in the current directory using 

isql: 

CREATE DATABASE "employee.gdb"; 

The next embedded SQL statement creates a database with a page size of 2048 
bytes rather than the default of 1024: 
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See Also 

EXEC SQL 

CREATE DATABASE "employee.gdb" PAGE_SIZE 2048; 

The following embedded SQL statement creates a database stored in two files 
and specifies its default character set: 

EXEC SQL 

CREATE DATABASE "employee.gdb" 

DEFAULT CHARACTER SET IS08859_1 

FILE "employee.gdl" STARTING AT PAGE lOOOI LENGTH 10000 PAGES; 

ALTER DATABASE, DROP DATABASE 

For more information about secondary files, character set specification, and col¬ 
lation order, see the Data Definition Guide. 

For more information about page size, see the Windows Client User's Guide. 


CREATE DOMAIN 



Creates a column definition that is global to the database. Available in SQL, 
DSQL, and isql. 

Syntax 

CREATE DOMAIN domain [AS] <datatype> 

[DEFAULT [literal \ NULL | USER}] 

[NOT NULL] [CHECK (<dom_search_condition>)] 

[COLLATE collation ]; 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Note 

The CQLLATE clause carmot be specified for BLQB columns. 

<datatype> = { 

{SMALLINT 1 INTEGER | FLOAT | DOUBLE PRECISION} [<array_dim>] 

1 {DECIMAL 1 NUMERIC} [{precision [, scale])] [<array_dim>] 

1 DATE [<array_dim>] 

1 [CHAR 1 CHARACTER | CHARACTER VARYING | VARCHAR] 

[ (1. . .32767) ] [<array_dim>] [CHARACTER SET charname] 

1 [NCHAR 1 NATIONAL CHARACTER | NATIONAL CHAR] 

[VARYING] [ (1. . .32767) ] [<array_dim>] 

1 BLOB [SUB_TYPE { int | subtype_name} ] [SEGMENT SIZE int] 

[CHARACTER SET charname] 

1 BLOB [{seglen [, subtype])] 

} 


<array_dim> = [x:y [, x:y ...]] 
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Note Outermost brackets, in bold, must be included when declaring arrays. 

<dom_search_condition> = { 

VALUE <operator> <val> 

I VALUE [NOT] BETWEEN <val> AND <val> 

I VALUE [NOT] LIKE <val> [ESCAPE <val>] 

I VALUE [NOT] IN (<val> [, <val> ...]) 

I VALUE IS [NOT] NULL 
I VALUE [NOT] CONTAINING <val> 

I VALUE [NOT] STARTING [WITH] <val> 

I (<dom_search_condition>) 

I NOT <dom_search_condition> 

I <dom_search_condition> OR <dom_search_condition> 

I <dom_search_condition> AND <dom_search_condition> 


<operator> = {= I < I > I <= I >= I !< I !> | <> | 


Argument 

Description 

domain 

Unique name for the domain. 

<datatype> 

SQL data type. 

DEFAULT 

Specifies a default column value that is entered when no other 
entry is made. Values: 

• //fera/—Inserts a specified string, numeric value, or date value. 

• NULL—Enters a NULL value. 

• USER—Enters the user name of the current user. Column 
must be of compatible character type to use the default. 

NOT NULL 

Specifies that the values entered in a column cannot be NULL. 

CHECK {<dom_ 
search_ condition>) 

Creates a single CHECK constraint for the domain. 

VALUE 

Placeholder for the name of a column eventually based on the 
domain. 

COLLATE collation 

Specifies a collation sequence for the domain. 


Description CREATE DOMAIN builds an inheritable column definition that acts as a tem¬ 
plate for coluirms defined with CREATE TABLE or ALTER TABLE. The domain 
definition contains a set of characteristics, which include: 

• Data type 

• An optional default value 

• Optional disallowing of NULL values 

• An optional CHECK constraint 

• An optional collation clause 
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The CHECK constraint in a domain definition sets a <dom_search_condition> that 
must be true for data entered into columns based on the domain. The CHECK 
constraint cannot reference any domain or column. 

Note Be careful when creating domains. It is possible to create a domain with 
contradictory constraints, such as declaring a domain NOT NULL, and 
assigning it a DEEAULT value of NULL. 

The data type specification for a CHAR, VARCHAR, or BLOB text domain defi¬ 
nition can include a CHARACTER SET clause to specify a character set for the 
domain. Otherwise, the domain uses the default database character set. Eor a 
complete list of character sets recognized by InterBase, see Appendix D: "Char¬ 
acter Sets and Collation Orders." 

If you do not specify a default character set, the character set defaults to NONE. 
Using character set NONE means that there is no character set assumption for 
columns; data is stored and retrieved just as you originally entered it. You can 
load any character set into a colrunn defined with NONE, but you cannot load 
that same data into another coluirm that has been defined with a different char¬ 
acter set. In these cases, no transliteration is performed between the source and 
destination character sets, so errors can occur during assignment. 

The COLLATE clause enables specification of a particular collation order for 
CHAR, VARCHAR, and BLOB text data t}^es. Choice of collation order is 
restricted to those supported for the domain's given character set, which is 
either the default character set for the entire database, or a different set defined 
in the CHARACTER SET clause as part of the data type definition. Eor a com¬ 
plete list of collation orders recognized by InterBase, see Appendix D: "Charac¬ 
ter Sets and Collation Orders." 

Columns based on a domain definition inherit all characteristics of the domain. 
The domain default, collation clause, and NOT NULL setting may be overrid¬ 
den when defining a colrunn based on a domain. A column based on a domain 
can add additional CHECK constraints to the domain CHECK constraint. 

Examples The following isql statement creates a domain that must have a positive value 
greater than 1,000, with a default value of 9,999. The keyword VALUE substi¬ 
tutes for the name of a column based on this domain. 

CREATE DOMAIN CUSTNO 
AS INTEGER 
DEFAULT 9999 
CHECK (VALUE > 1000); 
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The next isql statement limits the values entered in the domain to four specific 
values: 

CREATE DOMAIN PRODTYPE 
AS VARCHAR(12) 

CHECK (VALUE IN ("software", "hardware", "other", "N/A")); 

The following isql statement creates a domain that defines an array of CTTAR 
data t 5 ^e: 

CREATE DOMAIN DEPTARRAY AS CHAR(31) [4:5]; 

In the following isql example, the first statement creates a domain with USER as 
the default. The next statement creates a table that includes a column, 
ENTERED_BY, based on the USERNAME domain. 

CREATE DOMAIN USERNAME AS VARCHAR(20) 

DEFAULT USER; 

CREATE TABLE ORDERS (ORDER_DATE DATE, ENTERED_BY USERNAME, ORDER_AMT 
DECIMAL(8,2)); 

INSERT INTO ORDERS (ORDER_DATE, ORDER_AMT) 

VALUES ("l-MAY-93", 512.36); 

The INSERT statement does not include a value for the ENTERED_BY column, 
so InterBase automatically inserts the user name of the current user, JSMITH: 

SELECT * FROM ORDERS; 
l-MAY-93 JSMITH 512.36 

The next isql statement creates a BLOB domain with a text subt 5 q)e that has an 
assigned character set: 

CREATE DOMAIN DESCRIPT AS BLOB SUB_TYPE TEXT SEGMENT SIZE 80 
CHARACTER SET SJIS; 

See Also ALTER DOMAIN, ALTER TABLE, CREATE TABLE, DROP DOMAIN 

Eor more information about character set specification and collation orders, see 
the Data Definition Guide. 


CREATE EXCEPTION 

Creates a used-defmed error and associated message for use in stored proce¬ 
dures and triggers. Available in DSQL and isql. 

Syntax create exception name "<message>"; 
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Important 


Description 


Exampies 


See Aiso 


In SQL statements passed to DSQL, omit the terminating semicolon. In 
isql, the semicolon is a terminating symbol for the statement, so it must be 


included. 

Argument 

Description 

name 

Name associated with the exception message. Must be unique 
among exception names in the database. 

"<message>" 

Quoted string containing alphanumeric characters and punctua¬ 
tion. Maximum length: 78 characters. 


CREATE EXCEPTION creates an exception, a user-defined error with an associ¬ 
ated message. Exceptions maybe raised in triggers and stored procedures. 

Exceptions are global to the database. The same message or set of messages is 
available to all stored procedures and triggers in an application. Eor example, a 
database can have English and Erench versions of the same exception messages 
and use the appropriate set as needed. 

When raised by a trigger or a stored procedure, an exception: 

• Terminates the trigger or procedure in which it was raised and undoes 
any actions performed (directly or indirectly) by it. 

• Returns an error message to the calling application. In isql, the error 
message appears on the screen, imless output is redirected. 

Exceptions may be trapped and handled with a WHEN statement in a stored 
procedure or trigger. 

This isql statement creates the exception, UNKNOWN_EMP_ID: 

CREATE EXCEPTION UNKNOWN_EMP_ID "Invalid employee number or project 
id. 

The following statement from a stored procedure raises the previously created 
exception when SQLCODE -530 is set, which is a violation of a EOREIGN KEY 
constraint: 


WHEN SQLCODE -530 DO 

EXCEPTION UNKNOWN_EMP_ID; 


ALTER EXCEPTION, ALTER PROCEDURE, ALTER TRIGGER, CREATE 
PROCEDURE, CREATE TRIGGER, DROP EXCEPTION 

Eor more information on creating, raising, and handling exceptions, see the Data 
Definition Guide. 


42 


Language Reference 





CREATE GENERATOR 


CREATE GENERATOR 


Declares a generator to the database. Available in SQL, DSQL, and isql. 

Syntax create generator name; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

name 

Name for the generator. 


Description CREATE GENERATQR declares a generator to the database and sets its starting 
value to zero. A generator is a sequential number that can be automatically 
inserted in a column with the GEN_1D() function. A generator is often used to 
ensure a unique value in a PRIMARY KEY, such as an invoice number, that must 
uniquely identify the associated row. 

A database can contain any number of generators. Generators are global to the 
database, and can be used and updated in any transaction. InterBase does not 
assign duplicate generator values across transactions. 

After a generator is created, SET GENERATQR can set or change its current 
value. The generator can be used by writing a trigger, procedure, or SQL state¬ 
ment that calls GEN_1D(). 


Example The following isql script fragment creates the generator, EMPNQ_GEN, and the 
trigger, CREATE_EMPNQ. The trigger uses the generator to produce sequential 
numeric keys, incremented by 1, for the NEW.EMPNQ column: 

CREATE GENERATOR EMPNO_GEN; 

COMMIT; 

SET TERM !! ; 

CREATE TRIGGER CREATE_EMPNO FOR EMPLOYEES 
BEFORE INSERT 
POSITION 0 
AS BEGIN 

NEW.EMPNO = GEN_ID(EMPNO_GEN, 1); 

END 

SET TERM ; !! 

Important Because each statement in a stored procedure body must be terminated by 
a semicolon, you must define a different symbol to terminate the CREATE 
TRIGGER in isql. Use SET TERM before CREATE TRIGGER to specify a 
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terminator other than a semicolon. After CREATE TRIGGER, include 
another SET TERM to change the terminator back to a semicolon. 

See Also GENJDO, SET GENERATOR 


CREATE INDEX 


Greates an index on one or more columns in a table. Available in SQL, DSQL, 
and isql. 


Syntax create [unique] [ASC[ending] I DESC[ENDING]] 

INDEX index ON table {col [, col ...]); 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

UNIQUE 

Prevents insertion or updating of duplicate values into indexed 
columns. 

ASC[ENDING] 

Sorts columns in ascending order, the default order if none is 
specified. 

DESC[ENDING] 

Sorts columns in descending order. 

Index 

Unique name for the index. 

table 

Name of the table on which the index is defined. 

col 

Column in table to index. 


Description Greates an index on one or more columns in a table. Use GREATE INDEX to 
improve speed of data access. Using an index for columns that appear in a 
WHERE clause may improve search performance. 

Important BLQB columns and arrays cannot be indexed. 

A UNIQUE index cannot be created on a column or set of columns that already 
contains duplicate or NULL values. 

ASG and DESG specify the order in which an index is sorted. Eor faster response 
to queries that require sorted values, use the index order that matches the que¬ 
ry's QRDER BY clause. Both an ASG and a DESG index can be created on the 
same column or set of columns to access data in different orders. 
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Tip 

To improve index performance, use SET STATISTICS to recompute index 


selectivity, or rebuild the index by making it inactive, then active with 
sequential calls to ALTER INDEX. 

Examples 

The following isql statement creates a rmique index: 

CREATE UNIQUE INDEX PRODTYPEX ON PROJECT (PRODUCT, PROJ_NAME); 

The next isql statement creates a descending index: 

CREATE DESCENDING INDEX CHANGEX ON SALARY_HISTORY (CHANGE_DATE); 

The following isql statement creates a two-column index: 

CREATE INDEX NAMEX ON EMPLOYEE (LAST_NAME, FIRST_NAME); 

See Also 

ALTER INDEX, DROP INDEX, SELECT, SET STATISTICS 


CREATE PROCEDURE 


Syntax 

Creates a stored procedure, its input and output parameters, and its actions. 
Available in DSQL, and isql. 

CREATE PROCEDURE name 

[Iparam <datatype> [, param <datatype> ...])] 

[RETURNS <datatype> [, param <datatype> ...])] 

AS <procedure_body> [terminator] 

<procedure_body> = 

[<variable_declaration_list>] 

<block> 

<variable_declaration_list> = 

DECLARE VARIABLE var <datatype>; 

[DECLARE VARIABLE var <datatype>; ...] 

<block> = 

BEGIN 

<compound_statement> 

[<compound_statement> ...] 

END 


<compound_statement> = {<block> \ statement}} 
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Description 


<datatype> = { 

{SMALLINT I INTEGER | FLOAT | DOUBLE PRECISION} 

I {DECIMAL I NUMERIC} [{precision [, scale])] 

I DATE 

I {CHAR I CHARACTER | CHARACTER VARYING | VARCHAR} [(int)] 
[CHARACTER SET charname] 

I {NCHAR I NATIONAL CHARACTER | NATIONAL CHAR} 

[VARYING] [(int)]} 


Argument 

Description 

name 

Name of the procedure. Must be unique among procedure, table, 
and view names in the database. 

param <datatype> 

Input parameters that the calling program uses to pass values to 
the procedure: 

• pararTT—Name of the input parameter, unique for variables in 
the procedure. 

• <datatype> —An InterBase data type. 

RETURNS 

Output parameters that the procedure uses to return values to 

param <datatype> 

the calling program: 

• param—Name of the output parameter, unique for variables 
within the procedure. 

• <datatype> —An InterBase data type. 

The procedure returns the values of output parameters when it 
reaches a SUSPEND statement in the procedure body. 

AS 

Keyword that separates the procedure header and the procedure 
body. 

DECLARE 

Declares local variables used only in the procedure. Each decla¬ 

VARIABLE 

ration must be preceded by DECLARE VARIABLE and followed 

var <datatype> 

by a semicolon (;). var is the name of the local variable, unique 
for variables in the procedure. 

statement 

Any single statement in InterBase procedure and trigger lan¬ 
guage. Each statement (except BEGIN and END) must be fol¬ 
lowed by a semicolon (;). 

terminator 

Terminator defined by SET TERM which signifies the end of the 
procedure body. Used in isql only. 


CREATE PROCEDURE defines a new stored procedure to a database. A stored 
procedure is a self-contained program written in InterBase procedure and trig¬ 
ger language, and stored as part of a database's metadata. Stored procedures can 
receive input parameters from and return values to applications. 

InterBase procedure and trigger language includes all SQL data manipulation 
statements and some powerful extensions, including IE ... THEN ... ELSE, 
WHILE ... DO, EOR SELECT ... DO, exceptions, and error handling. 


46 


Language Reference 





CREATE PROCEDURE 


Important 


There are two t}^es of procedures: 

• Select procedures that an application can use in place of a table or view in 
a SELECT statement. A select procedure must be defined to return one or 
more values, or an error will result. 

• Executable procedures that an application can call directly, with the 
EXECUTE PROCEDURE statement. An executable procedure need not 
return values to the calling program. 

A stored procedure is composed of a header and a body. 

The procedure header contains: 

• The name of the stored procedure, which must be unique among proce¬ 
dure and table names in the database. 

• An optional list of input parameters and their data t 5 q)es that a procedure 
receives from the calling program. 

• RETURNS followed by a list of output parameters and their data t 5 q)es if 
the procedure returns values to the calling program. 

The procedure body contains: 

• An optional list of local variables and their data t 5 q)es. 

• A block of statements in InterBase procedure and trigger language, brack¬ 
eted by BEGIN and END. A block can itself include other blocks, so that 
there may be many levels of nesting. 

Because each statement in a stored procedure body must be terminated by 
a semicolon, you must define a different symbol to terminate the CREATE 
PROCEDURE statement in isql. Use SET TERM before CREATE 
PROCEDURE to specify a terminator other than a semicolon. After the 
CREATE PROCEDURE statement, include another SET TERM to change 
the terminator back to a semicolon. 

InterBase does not allow database changes that affect the behavior of an existing 
stored procedure (e.g., DROP TABLE, DROP EXCEPTION). To see all proce¬ 
dures defined for the current database or the text and parameters of a named 
procedure, use the isql internal commands SHOW PROCEDURES or SHOW 
PROCEDURE procedure. 

InterBase procedure and trigger language is a complete programming language 
for stored procedures and triggers. It includes: 

• SQL data manipulation statements: INSERT, UPDATE, DELETE, and 
singleton SELECT. 
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• SQL operators and expressions, including UDFs linked with the data¬ 
base and generators. 

• Powerful extensions to SQL, including assignment statements, control- 
flow statements, context variables (for triggers), event-posting state¬ 
ments, exceptions, and error-handling statements. 

The following table summarizes language extensions for stored procedures. For 
a complete description of each statement, see Chapter 3: "Procedure and Trigger 
Language Reference." 

Table 2-7: Procedure and Trigger Language Extensions 


Statement 

Description 

BEGIN . . . END 

Defines a block of statements that executes as one. 
The BEGIN keyword starts the block; the END key¬ 
word terminates it. Neither should be followed by a 
semicolon. 

variable = expression 

Assignment statement which assigns the value of 
expression to variable, a local variable, input parame¬ 
ter, or output parameter. 

r commentjext */ 

Programmer’s comment, where commentjext can be 
any number of lines of text. 

EXCEPTION 

exception_name 

Raises the named exception. An exception is a user- 
defined error, which returns an error message to the 
calling application unless handled by a WHEN state¬ 
ment. 

EXECUTE PROCEDURE 
proc_name[var[, var...]] 
[RETURNING_VALUES 
var[, var...]] 

EXIT 

FOR <select_statement> 

DO <compouncl_statement> 

Executes stored procedure, proc_name, with the 
listed input arguments, returning values in the listed 
output arguments following RETURNING_VALUES. 
Input and output arguments must be local variables. 
Jumps to the final END statement in the procedure. 
Repeats the statement or block following DO for 
every qualifying row retrieved by <select_statement>. 
<select_statement>: a normal SELECT statement, 
except the INTO clause is required and must come 
last. 

<compound_statement> 

Either a single statement In procedure and trigger lan¬ 
guage or a block of statements bracketed by BEGIN 
and END. 
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Table 2-7: Procedure and Trigger Language Extensions (Continued) 

Statement Description 

IF (<condition>) Tests <condition>, and if it is TRUE, performs the 

THEN <compound_statement> statement or block following THEN; othenwise, per- 
[ELSE <compound_statement>] forms the statement or block following ELSE, if 
present. 

<condition>: a Boolean expression (TRUE, FALSE, or 
UNKNOWN), generally two expressions as operands 
of a comparison operator. 

NEW.column New context variable that indicates a new column 

value in an INSERT or UPDATE operation. 

Old context variable that indicates a column value 
before an UPDATE or DELETE operation. 

Posts the event, event_name, or uses the value in col 
as an event name. 

In a SELECT procedure: 

• Suspends execution of procedure until next 
FETCH is issued by the calling application 

• Returns output values, if any, to the calling applica¬ 
tion. 

Not recommended for executable procedures. 

While <condition> is TRUE, keep performing 
<compound_statement>. First <condition> is tested, 
and if it is TRUE, then <compound_statement> is per¬ 
formed. This sequence is repeated until <condition> 
is no longer TRUE. 

Error-handling statement. When one of the specified 
errors occurs, performs <compound_statement>. 
WHEN statements, if present, must come at the end 
of a block, just before END. 

• <error>: EXCEPTION exception name, SQLCODE 
encode or GDSCODE number. 

• ANY: Handles any errors. 

Examples The following procedure, SUB_TOT_BUDGET, takes a department number as its 

input parameter, and returns the total, average, minimum, and maximum bud¬ 
gets of departments with the specified HEAD_DEPT. 

/* * Compute total, average, smallest, and largest department budget. 
*Parameters: 

* department id 

‘Returns: 

* total budget 

* average budget 


OLD.column 

POST EVENT event_name \ col 
SUSPEND 


WHILE {<condition>) 

DO <compound_statement> 


WHEN 

{<error> [, <error> ...] \ ANY} 
DO <compound_statement> 
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* min budget 

* max budget */ 

SET TERM !! ; 

CREATE PROCEDURE SUB_TOT_BUDGET (HEAD_DEPT CHAR(3)) 

RETURNS (tot_budget DECIMAL(12, 2), avg_budget DECIMAL(12, 2), 
min_budget DECIMAL(12, 2), max_budget DECIMAL(12, 2)) 

AS 

BEGIN 

SELECT SUM(BUDGET), AVG(BUDGET), MIN(BUDGET), MAX(BUDGET) 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :head_dept 

INTO :tot_budget, :avg_budget, :min_budget, :max_budget; 

EXIT; 

END ! ! 

SET TERM ; ! ! 

The following select procedure, ORG_CHART, displays an organizational chart: 

/* Display an org-chart. 

* Parameters: 


* Returns: 

* parent department 

* manager's job title 

* number of employees in the department */ 

CREATE PROCEDURE ORG_CHART 

RETURNS (HEAD_DEPT CHAR(25), DEPARTMENT CHAR(25), 

MNGR_NAME CHAR(20), TITLE CHAR(5), EMP_CNT INTEGER) 

AS 

DECLARE VARIABLE mngr_no INTEGER; 

DECLARE VARIABLE dno CHAR(3); 

BEGIN 

FOR SELECT H.DEPARTMENT, D.DEPARTMENT, D.MNGR_NO, D.DEPT_NO 
FROM DEPARTMENT d 

LEFT OUTER JOIN DEPARTMENT H ON D.HEAD_DEPT = H.DEPT_NO 
ORDER BY D.DEPT_NO 

INTO :head_dept, :department, :mngr_no, :dno 
DO 

BEGIN 

IF (:mngr_no IS NULL) THEN 
BEGIN 

MNGR_NAME = "—TBH— 

TITLE = 

END 

ELSE 

SELECT FULL_NAME, JOB_CODE 
FROM EMPLOYEE 
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HEAD_DEPT 


Corporate I 

Sales and I 

Pacific Rir 

Pacific Rir 

See Also 


WHERE EMP_NO = :mngr_no 
INTO :mngr_name, :title; 

SELECT COUNT(EMP_NO) 

FROM EMPLOYEE 
WHERE DEPT_NO = :dno 
INTO :emp_cnt; 

SUSPEND; 

END 
END ! ! 

When ORG_CHART is invoked, for example in the following isql statement: 

SELECT * FROM ORG_CHART 

It displays the department name for each department, which department it is in, 
the department manager's name and title, and the number of employees in the 
department. 


DEPARTMENT 


MNGR_NAME TITLE EMP_CNT 


Corporate Headquarters Bender, Oliver H. CEO 

Sales and Marketing MacDonald, Mary S. VP 

Pacific Rim Headquarters Baldwin, Janet Sales 

Field Office: Japan Yamamoto, Takashi SRep 


Headquarters Field Office: Singapore —TBH— 0 

ORG_CHART must be used as a select procedure to display the full organiza¬ 
tion. If called with EXECUTE PROCEDURE, the first time it encounters the 
SUSPEND statement, it terminates, returning the information for Corporate 
Headquarters only 

ALTER EXCEPTION, ALTER PROCEDURE, CREATE EXCEPTION, DROP 
EXCEPTION, DROP PROCEDURE, EXECUTE PROCEDURE, SELECT 

For more information on creating and using procedures, see the Data Definition 
Guide. 

For a complete description of the statements in procedure and trigger language, 
see Chapter 3: "Procedure and Trigger Language Reference." 
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CREATE SHADOW 

Creates one or more duplicate, in-sync copies of a database. Available in SQL, 
DSQL, and isql. 

Syntax create shadow set_nurn [AUTO | MANUAL] [CONDITIONAL] 

"Kfilespeo" [LENGTH [ = ] int [PAGE[S]]] 

[<secondary_flle>]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<secondary_file> = FILE ”<filespec>" [<fileinfo>] [<secondary_file>] 


<fileinfo> = LENGTH [=] int [PAGE[S]] | STARTING [AT [PAGE]] int 
[ <flleinfo>] 


Argument 

Description 

set_num 

Positive integer that designates a shadow set to which all subse¬ 
quent files listed in the statement belong. 

AUTO 

Specifies the default access behavior for databases in the event 
of shadow unavailability. All attachments and accesses succeed; 
references to the shadow are deleted and the shadow file is 
detached. 

MANUAL 

Specifies that database attachments and accesses fail until a 
shadow becomes available, or all references to the shadow are 
removed from the database. 

CONDITIONAL 

Creates a new shadow, allowing shadowing to continue if the pri¬ 
mary shadow becomes unavailable or if the shadow replaces the 
database due to disk failure. 

"<filespec>" 

Explicit path name and file name for the shadow file. Shadow file 
specifications cannot include a node name. 

LENGTH [=] int 
[PAGE[S]] 

Length in database pages of an additional shadow file. Page size 
is determined by page size of the database itself. 

<secondary_file> 

Specifies the length of a primary or secondary shadow file. Use 
for primary file only if defining a secondary file in the same state¬ 
ment. 

STARTING [AT 
[PAGE]] int 

Starting page number at which a secondary shadow file begins. 


Description CREATE SHADQW is used to guard against loss of access to a database by 

establishing one or more copies of the database on secondary storage devices. 
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Each copy of the database consists of one or more shadow files, referred to as a 
shadow set. Each shadow set is designated by a unique positive integer. 

Disk shadowing has three components: 

• A database to shadow. 

• The RDB$EILES system table, which lists shadow files and other infor¬ 
mation about the database. 

• A shadow set, consisting of one or more shadow files. 

When CREATE SHADOW is issued, a shadow is established for the database 
most recently attached by an application. A shadow set can consist of one or 
multiple files. In case of disk failure, the database administrator (DBA) activates 
the disk shadow so that it can take the place of the database. If CONDITIONAL 
is specified, then when the DBA activates the disk shadow to replace an actual 
database, a new shadow is established for the database. 

If a database is larger than the space available for a shadow on one disk, use the 
<secondaryJile> option to define multiple shadow files. Multiple shadow files 
can be spread over several disks. 

Tip To add a secondary file to an existing disk shadow, drop the shadow with 
DROP SHADOW and use CREATE SHADOW to recreate it with the 
desired number of files. 

Examples The following isql statement creates a single, automatic shadow file for 
employee.gdb: 

CREATE SHADOW 1 AUTO "employee.shd"; 

The next isql statement creates a conditional, single, automatic shadow file for 
employee.gdb: 

CREATE SHADOW 2 CONDITIONAL "employee.shd" LENGTH 1000; 

The following isql statements create a multiple-file shadow set for the 
employee.gdb database. The first statement specifies starting pages for the shadow 
files; the second statement specifies the number of pages for the shadow files. 

CREATE SHADOW 3 AUTO 
"employee.shl" 

FILE "employee.sh2" 

STARTING AT PAGE 1000 
FILE "employee.sh3" 

STARTING AT PAGE 2000; 

CREATE SHADOW 4 MANUAL "employee.sdw" 

LENGTH 1000 

FILE "employee.shl" 
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See Also 

LENGTH 1000 

FILE "employee.sh2”; 

DROP SHADOW 

For more information about using shadows, see the Windows Client User's Guide. 


CREATE TABLE 



Creates a new table in an existing database. Available in SQL, DSQL, and isql. 

Syntax 

CREATE TABLE table [EXTERNAL [FILE] " <fllespec>" ] 

(<col_def> [, <col_def> \ <tconstraint> ...]); 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<col_def> = col {datatype \ COMPUTED [BY] (<expr>) \ domain] 

[DEFAULT {literal I NULL | USER}] 

[NOT NULL] [<col_constraint>] 

[COLLATE collation] 

Note 

The CQLLATE clause carmot be specified for BLQB columns. 

<datatype> = { 

[SMALLINT 1 INTEGER | FLOAT | DOUBLE PRECISION} [<array_dlm>] 

1 {DECIMAL 1 NUMERIC} [{precision [, scale])] [<array_dim>] 

1 DATE [<array_dim>] 

1 [CHAR 1 CHARACTER | CHARACTER VARYING | VARCHAR] 

[ (int) ] [<array_dim>] [CHARACTER SET charname] 

1 [NCHAR 1 NATIONAL CHARACTER | NATIONAL CHAR] 

[VARYING] [(int)] [<array_dim>] 

1 BLOB [SUB_TYPE {int | subtype_name }] [SEGMENT SIZE int] 
[CHARACTER SET charname] 

1 BLOB [{seglen [, subtype])] 

} 

Note 

<array_dim> = [x:y [, x:y ...]] 

Qutermost brackets, in bold, must be included when declaring arrays. 

<expr> = A valid SQL expression that results in a single value. 

<col_constraint> = [CONSTRAINT constraint] <constraint_def> 

[ <col_constraint>] 

<constraint_def> = {UNIQUE | PRIMARY KEY 

1 CHECK (<search_condition>) 
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I REFERENCES other_table [(other_col [, other_col ...])]} 

<tconstraint> = CONSTRAINT constraint <tconstraint_def> 

[ <tconstraint>] 


<tconstraint_def> = {{PRIMARY KEY | UNIQUE} {col [, col ...]) 
I EOREIGN KEY (col [, col ...]) REEERENCES other_table 
I CHECK (<search_condltlon >)} 

<search_condltion> = 

{<val> <operator> {<val> \ {<select_one>)} 

I <val> [NOT] BETWEEN <val> AND <val> 

I <val> [NOT] LIKE <val> [ESCAPE <val>] 

I <val> [NOT] IN {<val> [, <val> ...] I <select_llst>) 

I <val> IS [NOT] NULL 

I <val> {[NOT] {= I < I >] I >= I <=] 

{ALL I SOME I ANY] {<select_llst>) 

I EXISTS (<select_expr>) 

I SINGULAR {<select_expr>) 

I <val> [NOT] CONTAINING <val> 

I <val> [NOT] STARTING [WITH] <val> 

I i<search_condition>) 

I NOT <search_condltion> 

I <search_conditlon> OR <search_condition> 

I <search_conditlon> AND <search_condltlon>} 


col l<array_dlin>] | -.variable 
I <constant> | <expr> | <functlon> 

I udf ([<val> [, <val> ...]]) 

I NULL I USER I RDB$DB_KEY | ? 

] [COLLATE collation] 

Note In SQL and isql, <val> cannot be a parameter placeholder (?). In DSQL and 
isql, <val> cannot be a variable. <expr> is any complex SQL statement or 
equation that produces a single value. 

<constant> = num \ "string" \ charsetname "string" 

<functlon> = { 

COUNT (* I [ALL] <val> \ DISTINCT <val>) 

I SUM ([ALL] <val> \ DISTINCT <val>) 

I AVG ([ALL] <val> \ DISTINCT <val>) 

I MAX ([ALL] <val> \ DISTINCT <val>) 

I MIN ([ALL] <val> | DISTINCT <val>) 

I CAST (<val> AS <datatype>) 

I UPPER {<val>) 

I GEN_ID {generator, <val>) 
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Description 


<operator> = {= | < | > | <= | >= | !< | !> | <> | !=} 

<select_one> = SELECT on a single column that returns exactly one 

<select_list> = SELECT on a single column that returns zero or more 
values. 

<select_expr> = SELECT on a list of values that returns zero or more 
values. 


Argument 

Description 

table 

Name for the table. Table name must be unique among table and 
procedure names in the database. 

EXTERNAL [FILE] 

Declares that data for the table to create resides in a table or file 

"<filespec>" 

outside the database. <fllespec> is the complete file specification 
of the external file or table. 

col 

Name for the table column; unique among column names in the 
table. 

<datatype> 

SOL data type for a column. 

COMPUTED [BY] 

Bases a column definition on an expression. The expression 

(<expr>) 

must return a single value, and cannot be an array or return an 
array. <expr> is any arithmetic expression that is valid for the 
data types in the columns. 

domain 

Name of an existing domain. 

COLLATE collation 

Specifies the collation order for the column or value. Collation 
order set at column level overrides domain level collation order. 

DEFAULT 

Specifies a default column value that is entered when no other 
entry is made. Values: 

• //fera/—Inserts a specified string, numeric value, or date value. 

• NULL—Enters a NULL value. 

• USER—Enters the user name of the current user. Column 
must be of compatible text type to use the default. 

Defaults set at column level override defaults set at the domain 
level. 

CONSTRAINT 

Places a named constraint on a table or column. A constraint is a 

constraint 

rule applied to a table’s structure or contents. If this clause is 
omitted, InterBase generates a system name for the constraint. 


CREATE TABLE establishes a new table, its columns, and integrity constraints in 
an existing database. The user who creates a table is the table's owner and has all 
privileges for it, including the ability to GRANT privileges to other users, trig¬ 
gers, and stored procedures. 
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CREATE TABLE supports several options for defining columns: 

• Local columns specify the name and data t 5 rpe for data entered into the 
column. 

• Computed columns are based on an expression. Column values are com¬ 
puted each time the table is accessed. If the data type is not specified, 
InterBase calculates an appropriate one. Columns referenced in the 
expression must exist before the column can be defined. 

• Domain-based columns inherit all the characteristics of a domain, but the 
column definition can include a new default value, a NOT NULL 
attribute, additional CHECK constraints, or a collation clause that over¬ 
rides the domain definition. It can also include additional column con¬ 
straints. 

• The data t 5 ^e specification for a CHAR, VARCHAR, or BLOB text col¬ 
umn definition can include a CHARACTER SET clause to specify a par¬ 
ticular character set for the single column. Otherwise, the column uses 
the default database character set. If the database character set is 
changed, all columns subsequently defined have the new character set, 
but existing columns are not affected. Eor a complete list of character sets 
recognized by InterBase, see Appendix D: "Character Sets and Collation 
Orders." 

• If you do not specify a default character set, the character set defaults to 
NONE. Using character set NONE means that there is no character set 
assumption for columns; data is stored and retrieved just as you origi¬ 
nally entered it. You can load any character set into a column defined 
with NONE, but you cannot load that same data into another column 
that has been defined with a different character set. In this case, no trans¬ 
literation is performed between the source and destination character sets, 
and errors may occur during assignment. 

• The COLLATE clause enables specification of a particular collation order 
for CHAR, VARCHAR, and BLOB text data t 5 q)es. Choice of collation 
order is restricted to those supported for the column's given character 
set, which is either the default character set for the entire database, or a 
different set defined in the CHARACTER SET clause as part of the data 
t 5 q)e definition. Eor a complete list of collation orders recognized by 
InterBase, see Appendix D: "Character Sets and Collation Orders." 

NOT NULL is an attribute that prevents the entry of NULL or unknown values 

in column. NOT NULL affects all INSERT and UPDATE operations on a column. 

Integrity constraints can be defined for a table when it is created. Integrity con¬ 
straints are rules that control the database and its contents, enforcing column-to- 

table and table-to-table relationships, and validating data entries. They span all 
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transactions that access the database and are automatically maintained by the 
system. CREATE TABLE can create the following t 5 ^es of integrity constraints: 

• PRIMARY KEY constraints are xmique identifiers for each row in a table. 
Values in this column or ordered set of columns carmot occur in more 
than one row. A PRIMARY KEY column must also define the NOT 
NULL attribute. A table can have only one PRIMARY KEY that can be 
defined on one or more columns. 

• UNIQUE keys ensure that no two rows have the same value for a speci¬ 
fied column or ordered set of coluirms. A unique column must also 
define the NOT NULL attribute. A table can have one or more UNIQUE 
keys. A UNIQUE key can be referenced by a EOREIGN KEY in another 
table. 

• Referential constraints ensure that values in a set of columns that define 
a EOREIGN KEY are the same as values in UNIQUE or PRIMARY KEY 
columns in a referenced table. Before the REEERENGES constraint can be 
added, the UNIQUE or PRIMARY KEY columns it references must 
already be defined in the referenced table. 

• GHEGK constraints enforce a <search_condition> that must be true for 
inserts or updates to the specified table. <search_condition> can require a 
certain combination or range of values or compare the value entered 
with data in other coluirms. 

Greating PRIMARY KEY and EOREIGN KEY constraints requires exclusive 
access to the database. 

Eor unnamed constraints, the system assigns a unique constraint name stored in 
the system table RDB$RELATION_GONSTRAINTS. 

Note Gonstraints are not enforced on expressions. 

Important A DEGLARE TABLE must precede GREATE TABLE in embedded applica¬ 
tions if the same SQL program both creates a table and inserts data in the 
table. 

The EXTERNAL EILE option creates a table whose data resides in an external 
file, rather than in the InterBase database. Use this option to: 

• Define an InterBase table composed of data from an external source, such 
as data in files managed by other operating systems or in non-database 
applications. 

• Transfer data to an existing InterBase table from an external file. 

Examples The following isql statement creates a simple table with a PRIMARY KEY: 
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CREATE TABLE COUNTRY 

COUNTRY COUNTRYNAME NOT NULL PRIMARY KEY, 
CURRENCY VARCHAR(IO) NOT NULL 


The next isql statement creates both a column-level and a table-level UNIQUE 
constraint: 

CREATE TABLE STOCK 

{MODEL SMALLINT NOT NULL UNIQUE, 

MODELNAME CHAR(IO) NOT NULL, 

ITEMID INTEGER NOT NULL, 

CONSTRAINT MOD_UNIQUE UNIQUE (MODELNAME, ITEMID)); 

The following isql statement illustrates table-level PRIMARY KEY, FOREIGN 
KEY, and CHECK constraints. The PRIMARY KEY constraint is based on three 
columns. This example also illustrates creating an array column of VARCHAR. 

CREATE TABLE JOB 

JOB_CODE JOBCODE NOT NULL, 

JOB_GRADE JOBGRADE NOT NULL, 

JOB_COUNTRY COUNTRYNAME NOT NULL, 

JOB_TITLE VARCHAR(25) NOT NULL, 

MIN_SALARY SALARY NOT NULL, 

MAX_SALARY SALARY NOT NULL, 

JOB_REQUIREMENT BLOB(400,1), 

LANGUAGE_REQ VARCHAR(15) [5], 

PRIMARY KEY {JOB_CODE, JOB_GRADE, JOB_COUNTRY), 

FOREIGN KEY {JOB_COUNTRY) REFERENCES COUNTRY (COUNTRY), 

CHECK {MIN_SALARY < MAX_SALARY) 


The next isql statement creates a table with a calculated column: 

CREATE TABLE SALARY_HISTORY 
EMP_NO EMPNO NOT NULL, 

CHANGE_DATE DATE DEFAULT "NOW" NOT NULL, 

UPDATER_ID VARCHAR{20) NOT NULL, 

OLD_SALARY SALARY NOT NULL, 

PERCENT_CHANGE DOUBLE PRECISION 
DEFAULT 0 
NOT NULL 

CHECK (PERCENT_CHANGE BETWEEN -50 AND 50), 
NEW_SALARY COMPUTED BY 

{OLD_SALARY + OLD_SALARY * PERCENT_CHANGE / 100), 
PRIMARY KEY {EMP_NO, CHANGE_DATE, UPDATER_ID), 

FOREIGN KEY {EMP_NO) REFERENCES EMPLOYEE {EMP_NO) 
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In the following isql statement the first column retains the default collating 
order for the database's default character set. The second column has a different 
collating order, and the third column definition includes a character set and a 
collating order. 

CREATE TABLE BOOKADVANCE (BOOKNO CHAR(6), 

TITLE CHAR(50) COLLATE IS08859_1, 

EUROPUB CHAR(50) CHARACTER SET IS08859_1 COLLATE FR_FR); 

See Also CREATE DOMAIN, DECLARE TABLE, GRANT, REVOKE 

Eor more information on creating metadata, using integrity constraints, external 
tables, data t5q5es, collation order, and character sets, see the Data Definition 
Guide. 


CREATE TRIGGER 

Creates a trigger, including when it fires, and what actions it performs. Available 
in DSQL, and isql. 

Syntax create trigger name FOR table 

[ACTIVE I INACTIVE] 

{BEFORE I AFTER} 

{DELETE I INSERT | UPDATE} 

[POSITION number] 

AS <trigger_body> terminator 

<trigger_body> = 

[ <variable_declaration_llst>] <block> 

<variable_declaration_list> = 

DECLARE VARIABLE variable <datatype>; 

[DECLARE VARIABLE variable <datatype>; ...] 

<block> = 

BEGIN 

<compound_statement> 
l<compound_statement> ...] 

END 

<compound_statement> = {<block> | statement}} 

<datatype> = { 

[SMALLINT I INTEGER | FLOAT | DOUBLE PRECISION} 

I [DECIMAL I NUMERIC} [(precision [, scale])] 

I DATE I {CHAR | CHARACTER | CHARACTER VARYING I VARCHAR} 

[(int)] [CHARACTER SET charname] 
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Description 


I {NCHAR I NATIONAL CHARACTER | NATIONAL CHAR} 
[VARYING] [(int)]} 


Argument 

Description 

name 

Name of the trigger. The name must be unique in the database. 

table 

Name of the table or view that causes the trigger to fire when the 
specified operation occurs on the table or view. 

ACTIVE 1 INACTIVE 

Optional. Specifies trigger action at transaction end: 

• ACTIVE: (Default) Trigger takes effect. 

• INACTIVE: Trigger does not take effect. 

BEFORE 1 AFTER 

Required. Specifies whether the trigger fires: 

• BEFORE: Before associated operation. 

• AFTER: After associated operation. 

Associated operations are DELETE, INSERT, or UPDATE. 

DELETE 1 INSERT 

1 UPDATE 

Specifies the table operation that causes the trigger to fire. 

POSITION number 

Specifies firing order for triggers before the same action or after 
the same action, number must be an integer between 0 and 
32,767, inclusive. Lower-number triggers fire first. Default: 

0 = first trigger to fire. 

Triggers for a table need not be consecutive. Triggers on the 
same action with the same position number will fire in random 
order. 

DECLARE 

VARIABLE 
var <datatype> 

Declares local variables used only in the trigger. Each declara¬ 
tion must be preceded by DECLARE VARIABLE and followed by 
a semicolon (;). 

• var. Local variable name, unique in the trigger. 

• <datatype>\ The data type of the local variable. 

statement 

Any single statement in InterBase procedure and trigger lan¬ 
guage. Each statement except BEGIN and END must be fol¬ 
lowed by a semicolon (;). 

terminator 

Terminator defined by the SET TERM statement which signifies 
the end of the trigger body. Used in isql only. 


CREATE TRIGGER defines a new trigger to a database. A trigger is a self- 
contained program associated with a table or view that automatically performs 
an action when a row in the table or view is inserted, updated, or deleted. 

A trigger is never called directly. Instead, when an application or user attempts 
to INSERT, UPDATE, or DELETE a row in a table, any triggers associated with 
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Important 


that table and operation automatically execute, or fire. Triggers defined for 
UPDATE on non-updatable views fire even if no update occurs. 

A trigger is composed of a header and a body. 

The trigger header contains: 

• A trigger name, unique within the database, that distinguishes the trigger 
from all others. 

• A table name, identifying the table with which to associate the trigger. 

• Statements that determine when the trigger fires. 

The trigger body contains: 

• Am optional list of local variables and their data t 5 q)es. 

• A block of statements in InterBase procedure and trigger language, brack¬ 
eted by BEGIN and END. These statements are performed when the trig¬ 
ger fires. A block can itself include other blocks, so that there may be 
many levels of nesting. 

Because each statement in the trigger body must be terminated by a semi¬ 
colon, you must define a different symbol to terminate the trigger body 
itself. In isql, include a SET TERM statement before CREATE TRIGGER to 
specify a terminator other than a semicolon. After the body of the trigger, 
include another SET TERM to change the terminator back to a semicolon. 

A trigger is associated with a table. The table owner and any user granted privi¬ 
leges to the table automatically have rights to execute associated triggers. 

Triggers can be granted privileges on tables, just as users or procedures can be 
granted privileges. Use the GRANT statement, but instead of using TO username, 
use TO TRIGGER trigger_name. Triggers' privileges can be revoked similarly 
using REVOKE. 

When a user performs an action that fires a trigger, the trigger will have privi¬ 
leges to perform its actions if one of the following conditions is true: 

• The trigger has privileges for the action. 

• The user has privileges for the action. 

InterBase procedure and trigger language is a complete programming language 
for stored procedures and triggers. It includes: 

• SQL data manipulation statements: INSERT, UPDATE, DELETE, and 
singleton SELECT. 
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• SQL operators and expressions, including UDFs linked with the calling 
application and generators. 

• Powerful extensions to SQL, including assignment statements, control- 
flow statements, context variables, event-posting statements, exceptions, 
and error-handling statements. 

The following table summarizes language extensions for triggers. For a com¬ 
plete description of each statement, see Chapter 3: "Procedure and Trigger Lan¬ 
guage Reference." 


Table 2-8: Procedure and Trigger Language Extensions 


Statement 
BEGIN . . . END 


variable = expression 


r commentjext */ 

EXCEPTION 

exception_name 


EXECUTE PROCEDURE 
proc_name[var[, var...]] 
[RETURNING_VALUES 
var[, var...]] 

EXIT 

FOR <select_statement> 

DO <compouncl_statement> 


<compound_statement> 


Description 

Defines a block of statements that executes as one. 
The BEGIN keyword starts the block; the END key¬ 
word terminates it. Neither should be followed by a 
semicolon. 

Assignment statement which assigns the value of 
expression to variable, a local variable, input parame¬ 
ter, or output parameter. 

Programmer’s comment, where commentjext can be 
any number of lines of text. 

Raises the named exception. An exception is a user- 
defined error, which returns an error message to the 
calling application unless handled by a WHEN state¬ 
ment. 

Executes stored procedure, proc_name, with the 
listed input arguments, returning values in the listed 
output arguments following RETURNING_VALUES. 
Input and output arguments must be local variables. 
Jumps to the final END statement in the procedure. 
Repeats the statement or block following DO for 
every qualifying row retrieved by <select_statement>. 
<select_statement>: a normal SELECT statement, 
except the INTO clause is required and must come 
last. 

Either a single statement in procedure and trigger lan¬ 
guage or a block of statements bracketed by BEGIN 
and END. 
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Table 2-8: Procedure and Trigger Language Extensions (Continued) 

Statement Description 


IF (<condition>) 

THEN <compound_statement> 
[ELSE <compound_statement>] 


NEW. column 
OLD.column 

POST EVENT event_name \ col 

WHILE {<conditlon>) 

DO <compound_statement> 


WHEN 

{<error> [, <error> ...] | ANY} 
DO <compound_statement> 


Examples 


Tests <condition>, and if it is TRUE, performs the 
statement or block following THEN; othenwise, per¬ 
forms the statement or block following ELSE, if 
present. 

<condition>: a Boolean expression (TRUE, FALSE, or 
UNKNOWN), generally two expressions as operands 
of a comparison operator. 

New context variable that indicates a new column 
value in an INSERT or UPDATE operation. 

Old context variable that Indicates a column value 
before an UPDATE or DELETE operation. 

Posts the event, event_name, or uses the value in col 
as an event name. 

While <condltion> is TRUE, keep performing 
<compound_statement>. First <conditlon> is tested, 
and if it is TRUE, then <compound_statement> is per¬ 
formed. This sequence is repeated until <condition> 
is no longer TRUE. 

Error-handling statement. When one of the specified 
errors occurs, performs <compound_statement>. 
WHEN statements, if present, must come at the end 
of a block, just before END. 

• <error>: EXCEPTION exceptlon_name, SQLCODE 
encode or GDSCODE number. 

• ANY: Handles any errors. 


The following trigger, SAVE_SALARY_CHANGE, makes correlated updates to 
the SALARY_HISTORY table when a change is made to an employee's salary in 
the EMPLOYEE table: 


SET TERM !! ; 

CREATE TRIGGER SAVE_SALARY_CHANGE FOR EMPLOYEE 

AFTER UPDATE AS 

BEGIN 

IF (OLD.SALARY <> NEW.SALARY) THEN 
INSERT INTO SALARY_HISTORY 

(EMP_NO, CHANGE_DATE, UPDATER_ID, OLD_SALARY, PERCENT_CHANGE) 
VALUES {OLD.EMP_NO, "now", USER,OLD.SALARY, 

(NEW.SALARY - OLD.SALARY) * 100 / OLD.SALARY); 

END ! ! 

SET TERM ; !! 
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The following trigger, SET_CUST_NO, uses a generator to create unique cus¬ 
tomer numbers when a new customer record is inserted in the CUSTOMER 
table: 

SET TERM !! ; 

CREATE TRIGGER SET_CUST_NO FOR CUSTOMER 

BEFORE INSERT AS 

BEGIN 

NEW.CUST_NO = GEN_ID {CUST_NO_GEN, 1); 

END ! ! 

SET TERM ; !! 

The following trigger, POST_NEW_ORDER, posts an event named "new_order" 
whenever a new record is inserted in the SALES table: 

SET TERM !! ; 

CREATE TRIGGER POST_NEW_ORDER FOR SALES 

AFTER INSERT AS 

BEGIN 

POST_EVENT "new_order"; 

END ! ! 

SET TERM ; !! 

The following four fragments of trigger headers demonstrate how the 
POSITION option determines trigger firing order: 

CREATE TRIGGER A FOR accounts 
BEFORE UPDATE 

POSITION 5 . . . /^Trigger body follows*/ 

CREATE TRIGGER B FOR accounts 
BEFORE UPDATE 

POSITION 0 . . . /*Trigger body follows*/ 

CREATE TRIGGER C FOR accounts 
AFTER UPDATE 

POSITION 5 . . . /*Trigger body follows*/ 

CREATE TRIGGER D FOR accounts 
AFTER UPDATE 

POSITION 3 . . . /*Trigger body follows*/ 

When this update takes place: 

UPDATE accounts SET account_status = "on_hold" 

WHERE account_balance <0; 

The triggers fire in this order: 

1. Trigger B fires. 

2. Trigger A fires. 

3. The update occurs. 
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4. Trigger D fires. 

5. Trigger C fires. 

See Also ALTER EXCEPTION, ALTER TRIGGER, GREATE EXGEPTION, GREATE 

PROGEDURE, DROP EXGEPTION, DROP TRIGGER, EXEGUTE PROGEDURE 

For more information on creating and using triggers, see the Data Definition 
Guide. 

For a complete description of the statements in procedure and trigger language, 
see Ghapter 3: "Procedure and Trigger Language Reference." 


CREATE VIEW 

Greates a new view of data from one or more tables. Available in SQL, DSQL, 
and isql. 

Syntax create view name [{vlew_col [, vlew_col ...])] 

AS <select> [WITH CHECK OPTION]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

name 

Name for the view. Must be unique among all view, table, and 
procedure names in the database. 

viewcol 

Names the columns for the view. Column names must be unique 
among all column names in the view. Required if the view 
includes columns based on expressions; otherwise optional. 
Default: Column name from the underlying table. 

<select> 

Specifies the selection criteria for rows to be included in the view. 

WITH CHECK 
OPTION 

Prevents INSERT or UPDATE operations on an updatable view if 
the INSERT or UPDATE violates the search condition specified 
in the WHERE clause of the view’s <select>. 


Description GREATE VIEW describes a view of data based on one or more underlying tables 
in the database. The rows to return are defined by a SELEGT statement that lists 
columns from the source tables. Qnly the view definition is stored in the data¬ 
base; a view does not directly represent physically stored data. It is possible to 
perform select, project, join, and rmion operations on views as if they were 
tables. 
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The user who creates a view is its owner and has all privileges for it, including 
the ability to GRANT privileges to other users, triggers, and stored procedures. 
A user may have privileges to a view without having access to its base tables. 
When creating views: 

• A read-only view requires SELECT privileges for any xmderlying tables. 

• An updatable view requires ALL privileges to the underlying tables. 

The view_col option ensures that the view always contains the same columns and 
that the columns always have the same view-defined names. 

View column names correspond in order and number to the columns listed in 
the <select>, so specify all view column names or none. 

A viewjeol definition can contain one or more columns based on an expression 
that combines the outcome of two columns. The expression must return a single 
value, and cannot return an array or array element. If the view includes an 
expression, the view-column option is required. 

Note Any columns used in the value expression must exist before the expression 
can be defined. 

A SELECT statement clause cannot include the ORDER BY clause. 

When SELECT * is used rather than a column list, order of display is based on 
the order in which columns are stored in the base table. 

WITH CHECK OPTION enables InterBase to verify that a row added to or 
updated in a view is able to be seen through the view before allowing the opera¬ 
tion to succeed. Do not use WITH CHECK OPTION for read-only views. 

Note DSQL does not support view definitions containing UNION clauses. To 
create such a view, use embedded SQL. 

A view is updatable if: 

• It is a subset of a single table or another updatable view. 

• All base table columns excluded from the view definition allow NULL 
values. 

• The view's SELECT statement does not contain subqueries, a DISTINCT 
predicate, a HAVING clause, aggregate frmctions, joined tables, user- 
defined frmctions, or stored procedures. 

If the view definition does not meet these conditions, it is considered read-only. 

Note Read-only views can be updated by using a combination of user-defined 
referential constraints, triggers, and rmique indexes. 
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CREATE VIEW 


Examples The following isql statement creates an updatable view: 

CREATE VIEW SNOW_LINE (CITY, STATE, SNOW_ALTITUDE) AS 
SELECT CITY, STATE, ALTITUDE 
FROM CITIES 
WHERE ALTITUDE > 5000; 

The next isql statement uses a nested query to create a view: 

CREATE VIEW RECENT_CITIES AS 

SELECT STATE, CITY, POPULATION FROM CITIES WHERE STATE IN 
(SELECT STATE FROM STATES WHERE STATEHOOD > "1-JAN-1850"); 

In an updatable view, the WITH CHECK OPTION prevents any inserts or 
updates through the view that do not satisfy the WHERE clause of the CREATE 
VIEW SELECT statement: 

CREATE VIEW HALF_MILE_CITIES AS 

SELECT CITY, STATE, ALTITUDE FROM CITIES 
WHERE ALTITUDE > 2500 
WITH CHECK OPTION; 

The WITH CHECK OPTION clause in the view would prevent the following 
insertion: 

INSERT INTO HALF_MILE_CITIES (CITY, STATE, ALTITUDE) 

VALUES ("Chicago", "Illinois", 250); 

On the other hand, the following UPDATE would be permitted: 

INSERT INTO HALF_MILE_CITIES (CITY, STATE, ALTITUDE) 

VALUES ("Truckee", "California", 2736); 

The WITH CHECK OPTION clause does not allow updates through the view 
which change the value of a row so that the view cannot retrieve it. Por example, 
the WITH CHECK OPTION in the HALP_M1LE_C1T1ES view prevents the fol¬ 
lowing update: 

UPDATE HALF_MILE_CITIES 
SET ALTITUDE = 2000 
WHERE STATE = "NY"; 

The next isql statement creates a view that joins two tables, and so is read-only: 

CREATE VIEW PHONE_LIST AS SELECT 

EMP_NO, FIRST_NAME, LAST_NAME, PHONE_EXT, LOCATION, PHONE_NO 
FROM EMPLOYEE, DEPARTMENT 

WHERE EMPLOYEE.DEPT_NO = DEPARTMENT.DEPT_NO; 

See Also CREATE TABLE, DROP VIEW, GRANT, INSERT, REVOKE, SELECT, UPDATE 
Por a complete discussion of views, see the Data Definition Guide. 
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DECLARE CURSOR 

Defines a cursor for a table by associating a name with the set of rows specified 
in a SELECT statement. Available in SQL and DSQL. 

Syntax SQL form: 

DECLARE cursor CURSOR FOR <select> [FOR UPDATE OF <col> [, <COl>..; 

DSQL form: 

DECLARE cursor CURSOR FOR <statement_id> 

BLQB form: 

See DECLARE CURSQR (BLQB) 


Argument 

Description 

cursor 

Name for the cursor. 

<select> 

Determines which rows to retrieve. SOL only. 

FOR UPDATE OF 

Enables UPDATE and DELETE of specified column for retrieved 

<col> [, <col >...] 

rows. 

<statement_id> 

SQL statement name of a previously prepared statement, which, 
in this case, must be a SELECT statement. DSQL only. 


Description DECLARE CURSQR defines the set of rows that can be retrieved using the cur¬ 
sor it names. It is the first member of a group of table cursor statements that 
must be used in sequence. 

<select> specifies a SELECT statement that determines which rows to retrieve. 
The SELECT statement cannot include INTQ or QRDER BY clauses. 

The EQR UPDATE QE clause is necessary for updating or deleting rows using 
the WHERE CURRENT QE clause with UPDATE and DELETE. 

A cursor is a one-way pointer into the ordered set of rows retrieved by the select 
expression in the DECLARE CURSQR statement. It enables sequential access to 
retrieved rows in turn. There are four related cursor statements: 


Stage Statement Purpose 

1 DECLARE Declares the cursor. The SELECT statement determines rows 

CURSOR retrieved for the cursor. 

2 OPEN Retrieves the rows specified for retrieval with DECLARE 

CURSOR. The resulting rows become the cursor's active set. 
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DECLARE CURSOR (BLOB) 


Stage Statement Purpose 

3 FETCH Retrieves the current row from the active set, starting with the 

first row. Subsequent FETCH statements advance the cursor 
through the set. 

4 CLOSE Cioses the cursor and releases system resources. 

Examples The following embedded SQL statement declares a cursor with a search condi¬ 
tion: 

EXEC SQL 

DECLARE C CURSOR FOR 
SELECT CUST_NO, ORDER_STATUS 
FROM SALES 

WHERE ORDER_STATUS IN ("open", "shipping"); 

The next DSQL statement declares a cursor for a previously prepared statement, 
QUERYl: 

DECLARE Q CURSOR FOR QUERYl 

See Also CLOSE, DECLARE CURSOR (BLOB), EETCH, OPEN, PREPARE, SELECT 


DECLARE CURSOR (BLOB) 


Declares a BLOB cursor for read or insert. Available in SQL. 

Syntax declare cursor CURSOR FOR 

{READ BLOB column FROM table 
I INSERT BLOB column INTO table} 

[FILTER [FROM subtype] TO subtype] 
[MAXIMUM_SEGMENT length]; 


Argument 

Description 

cursor 

Name for the BLOB cursor. 

column 

Name of the BLOB column. 

table 

Table name. 

READ BLOB 

Declares a read operation on the BLOB. 

INSERT BLOB 

Declares a write operation on the BLOB. 

[FILTER [FROM 
subtype] TO subtype] 

Specifies optional BLOB filters used to translate a BLOB from 
one user-specified format to another, subtype determines which 
filters are used for translation. 

MAXIMUM 

SEGMENT length 

Length of the local variable to receive the BLOB data after a 
FETCH operation. 


70 


Language Reference 









DECLARE EXTERNAL FUNCTION 


Description 

Declares a cursor for reading or inserting BLOB data. A BLOB cursor can be 
associated with only one BLOB column. 

To read partial BLOB segments when a host-language variable is smaller than 
the segment length of a BLOB, declare the BLOB cursor with the 
MAX1MUM_SEGMENT clause. If length is less than the BLOB segment, EETCH 
returns length bytes. If the same or greater, it returns a full segment (the default). 

Exampies 

The following embedded SQL statement declares a READ BLOB cursor and uses 
the MAXIMUM_SEGMENT option: 

EXEC SQL 

DECLARE BC CURSOR FOR 

READ BLOB JOB_REQUIREMENT FROM JOB MAXIMUM_SEGMENT 40; 

The next embedded SQL statement declares an INSERT BLOB cursor: 

EXEC SQL 

DECLARE BC CURSOR FOR 

INSERT BLOB JOB_REQUIREMENt INTO JOB; 

See Aiso 

CLOSE (BLOB), FETCH (BLOB), INSERT CURSOR(BLOB), OPEN (BLOB) 


DECLARE EXTERNAL FUNCTION 



Declares an existing user-defined function (UDE) to the database. Available in 
SQL, DSQL, and isql. 

Syntax 

DECLARE EXTERNAL FUNCTION name [<datatype> | CSTRING (int) 

[, <datatype> \ CSTRING (int) ...]] 

RETURNS {<datatype> [BY VALUE] | CSTRING (int)} 

ENTRY_POINT " <entryname>" 

MODULE_NAME " <modulename>"; 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of the DDF. 

<datatype> Data type of an input or return parameter. All input parameters 

are passed to a DDF by reference. Return parameters can be 
passed by value. Cannot be an array element. 

RETURNS Specifies the return value of a function. 
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DECLARE FILTER 


Argument 

Description 

BY VALUE 

Specifies that a return value should be passed by value, rather 
than by reference. 

CSTRING (/nf) 

Specifies a UDF that returns a null-terminated string ;nf bytes in 
length. 

" <entryname>" 

Quoted string specifying the name of the UDF as stored in the 
UDF library. 

" <modulename>" 

Quoted file specification identifying the object module in which 
the UDF resides. 


Description DECLARE EXTERNAL FUNCTION provides information about a UDF to the 

database: where to find it, its name, the input parameters it requires, and the sin¬ 
gle value it returns. A UDF exists in a library outside the database. 

''<entryname>'' is the actual name of the fimction as stored in the UDF library. It 
does not have to match the name of the UDF as stored in the database. 

Important Do not use DECLARE EXTERNAL FUNCTION when creating a database 
on a NetWare server. UDF libraries carmot be created or used on NetWare 
servers. 


Exampie The following isql statement declares the function, TOPS(), to a database: 

DECLARE EXTERNAL FUNCTION TOPS 
CHAR(256), INTEGER, BLOB 
RETURNS INTEGER BY VALUE 
ENTRY_POINT "tel" MODULE_NAME "tml"; 

See Aiso DROP EXTERNAL FUNCTION 

For more information about writing UDFs, see the Data Definition Guide. 

For more information about using UDFs in embedded applications, see the Pro¬ 
grammer's Guide. 


DECLARE FILTER 

Declares an existing BLOB filter to a database. Available in SQL, DSQL, and isql. 

Syntax declare filter filter 

INPUT_TYPE subtype OUTPUT_TYPE subtype 

ENTRY_POINT ”<entryname>" MODULE_NAME ”<inodulename>"} 
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DECLARE FILTER 


Important 


Description 


Important 

Exampie 

See Aiso 


In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

filter 

Name of the filter. Must be unique among filter names in the 
database. 

INPUT_TYPE 

subtype 

Specifies the BLOB subtype from which data is to be converted. 

OUTPUT_TYPE 

subtype 

Specifies the BLOB subtype into which data is to be converted. 

" <entryname>" 

Ouoted string specifying the name of the BLOB filter as stored in 
a linked library. 

" <modulename>" 

Ouoted file specification identifying the object module in which 
the filter is stored. 


DECLARE EILTER provides information about an existing BLOB filter to the 
database: where to find it, its name, and the BLOB subt 5 ^es it works with. A 
BLOB filter is a user-written program that converts data stored in BLOB columns 
from one subt 5 ^e to another. 

INPUT_TYPE and OUTPUT_TYPE together determine the behavior of the 
BLOB filter. Each filter declared to the database should have a unique combina¬ 
tion of INPUT_TYPE and OUTPUT_TYPE integer values. InterBase provides a 
built-in t}q5e of 1, for handling text. User-defined t 5 q)es must be expressed as 
negative values. 

"<entryname>" is the name of the BLOB filter stored in the library. When an 
application uses a BLOB filter, it calls the filter function with this name. 

Do not use DECLARE FILTER when creating a database on a NetWare 
server. BLOB filters cannot be created or used on NetWare servers. 

The following isql statement declares a BLOB filter: 

DECLARE FILTER DESC_FILTER 
INPUT_TYPE 1 
OUTPUT_TYPE -4 
ENTRY_POINT "desc_fliter" 

MODULE_NAME "FILTERLIB"; 

DROP FILTER 

For instructions on writing BLOB filters, see the Programmer's Guide. 

For more information about BLOB subt 5 q)es, see the Data Definition Guide. 
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DECLARE STATEMENT 


DECLARE STATEMENT 


Identifies d}mamic SQL statements before they are prepared and executed in an 
embedded program. Available in SQL. 

Syntax declare <statement> STATEMENT; 


Argument 

Description 

<statement> 

Name of an SQL variable for a user-supplied SQL statement to 
prepare and execute at run time. 


Description DECLARE STATEMENT names an SQL variable for a user-supplied SQL state¬ 
ment to prepare and execute at rim time. DECLARE STATEMENT is not exe¬ 
cuted, so it does not produce run-time errors. The statement provides internal 
documentation. 


Exampie The following embedded SQL statement declares Q1 to be the name of a string 
for preparation and execution. 

EXEC SQL 

DECLARE Q1 STATEMENT; 

See Aiso EXECUTE, EXECUTE IMMEDIATE, PREPARE 


DECLARE TABLE 

Describes the structure of a table to the preprocessor, gpre, before it is created 
with CREATE TABLE. Available in SQL. 


Syntax declare table TABLE {<table_def>); 


Argument 

Description 

table 

Name of the table that will be created. Table names must be 
unique within the database. 

<table_def> 

Definition of the table. For complete table definition syntax, see 
CREATE TABLE. 


Description DECLARE TABLE causes gpre to store a table description. A table declaration is 
required if a table is both created and populated with data in the same program. 
If the declared table already exists in the database or if the declaration contains 
S 5 mtax errors, gpre returns an error. 
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DELETE 


Important 

Examples 


See Also 

DELETE 

Syntax 

Important 


When a table is referenced at run time, the column descriptions and data t 5 ^es 
are checked against the description stored in the database. If the table descrip¬ 
tion is not in the database and the table is not declared, or if column descriptions 
and data t 5 rpes do not match, the application returns an error. 

DECLARE TABLE can include an existing domain in a column definition, but 
must give the complete column description if the domain is not defined at com¬ 
pile time. 

DECLARE TABLE cannot include integrity constraints and column attributes, 
even if they are present in a subsequent CREATE TABLE statement. 

DECLARE TABLE carmot appear in a program that accesses multiple data¬ 
bases. 

The following embedded SQL statements declare and create a table: 

EXEC SQL 

DECLARE STOCK TABLE 
(MODEL SMALLINT, 

MODELNAME CHAR(IO), 

ITEMID INTEGER); 

EXEC SQL 

CREATE TABLE STOCK 
(MODEL SMALLINT NOT NULL UNIQUE, 

MODELNAME CHAR(10) NOT NULL, 

ITEMID INTEGER NOT NULL, CONSTRAINT MOD_UNIQUE UNIQUE (MODELNAME, 
ITEMID)); 

CREATE DOMAIN, CREATE TABLE 


Removes rows in a table or in the active set of a cursor. Available in SQL, DSQL, 
and isql. 

SQL and DSQL form: 

DELETE [TRANSACTION transaction] FROM table 

{[WHERE <search_condition>] \ WHERE CURRENT OF cursor]} 

Omit the terminating semicolon for DSQL. 

<search_condition> = Search condition as specified in SELECT, 
isql form: 

DELETE FROM TABLE [WHERE <search_condition >]; 
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DELETE 


Description 


Caution 


Exampies 


Argument 

Description 

TRANSACTION 

transaction 

Name of the transaction under control of which the statement is 
executed. SQL only. 

table 

Name of the table from which to delete rows. 

WHERE 

<search_condition> 

Search condition that specifies the rows to delete. Without this 
clause, DELETE affects all rows in the specified table or view. 

WHERE CURRENT 
OF cursor 

Specifies that the current row in the active set of cursor is to be 
deleted. 


DELETE specifies one or more rows to delete from a table or updatable view. 
DELETE is one of the database privileges controlled by the GRANT and 
REVOKE statements. 

The TRANSACTION clause can be used in multiple transaction SQL applica¬ 
tions to specify which transaction controls the DELETE operation. The 
TRANSACTION clause is not available in DSQL or isql. 

Eor searched deletions, the optional WHERE clause can be used to restrict dele¬ 
tions to a subset of rows in the table. 

Without a WHERE clause, a searched delete removes all rows from a table. 

When performing a positioned delete with a cursor, the WHERE CURRENT OF 
clause must be specified to delete one row at a time from the active set. 

The following isql statement deletes all rows in a table: 

DELETE FROM EMPLOYEE_PROJECT; 

The next embedded SQL statement is a searched delete in an embedded applica¬ 
tion. It deletes all rows where a host-language variable equals a column value. 

EXEC SQL 

DELETE FROM SALARY_HISTORY 
WHERE EMP_NO = : emp_num; 

The following embedded SQL statements use a cursor and the WHERE 
CURRENT QF option to delete rows from CITIES with a population less than 
the host variable, min_pop. They declare and open a cursor that finds qualifying 
cities, fetch rows into the cursor, and delete the current row pointed to by the 
cursor. 

EXEC SQL 

DECLARE SMALL_CITIES CURSOR FOR 
SELECT CITY, STATE 
FROM CITIES 
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WHERE POPULATION < :min_pop; 

EXEC SQL 

OPEN SMALL_CITIES; 

EXEC SQL 

FETCH SMALL_CITIES INTO :cityname, :statecode; 

WHILE (ISQLCODE) 

{ 

EXEC SQL 

DELETE FROM CITIES 

WHERE CURRENT OF SMALL_CITIES; 

EXEC SQL 

FETCH SMALL_CITIES INTO :cityname, :statecode; 

} 

EXEC SQL 

CLOSE SMALL_CITIES; 

See Also DECLARE CURSOR, FETCH, GRANT, OPEN, REVOKE, SELECT 

For more information about using cursors, see the Programmer's Guide. 


DESCRIBE 

Provides information about columns that are retrieved by a d5mamic SQL 
(DSQL) statement, or information about d5mamic parameters that statement 
passes. Available in SQL. 

Syntax describe [output I input] statement 

{INTO I USING} SQL DESCRIPTOR xsqlda; 


Argument 

Description 

OUTPUT 

Indicates that column information should be returned in the 
XSQLDA (default). 

INPUT 

Indicates that dynamic parameter information should be stored in 
the XSQLDA. 

statement 

A previously defined alias for the statement to DESCRIBE. 
Aliases are defined with PREPARE. 

{INTO 1 USING} SQL 
DESCRIPTOR xsqlda 

Specifies the XSQLDA to use for the DESCRIBE statement. 


Description DESCRIBE has two uses: 

• As a describe output statement, DESCRIBE stores into an XSQLDA a 
description of the columns that make up the select list of a previously 
prepared statement. If the PREPARE statement included an INTQ clause, 
it is unnecessary to use DESCRIBE as an output statement. 
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DESCRIBE 


• As a describe input statement, DESCRIBE stores into an XSQLDA a 

description of the d5mamic parameters that are in a previously prepared 
statement. 

DESCRIBE is one of a group of statements that process DSQL statements. 


Statement 

PREPARE 

DESCRIBE 

EXECUTE 

EXECUTE 

IMMEDIATE 


Purpose 

Readies a DSQL statement for execution. 

Fills in the XSQLDA with information about the statement. 
Executes a previously prepared statement. 

Prepares a DSQL statement, executes it once, and discards it. 


Separate DESCRIBE statements must be issued for input and output operations. 
The INPUT ke5rword must be used to store d5mamic parameter information. 

Important When using DESCRIBE for output, if the value returned in the sqld field in 
the XSQLDA is larger than the sqln field, you must: 

• Allocate more storage space for XSQLVAR structures. 

• Reissue the DESCRIBE statement. 

Note The same XSQLDA structure can be used for input and output if desired. 

Example The following embedded SQL statement retrieves information about the output 
of a SELECT statement: 

EXEC SQL 

DESCRIBE Q INTO xsqlda 

The next embedded SQL statement stores information about the dynamic 
parameters passed with a statement to be executed: 

EXEC SQL 

DESCRIBE INPUT Q2 USING SQL DESCRIPTOR xsqlda; 


See Also EXECUTE, EXECUTE IMMEDIATE, PREPARE 

Eor more information about DSQL programming and the XSQLDA, see the Pro¬ 
grammer's Guide. 
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DISCONNECT 


DISCONNECT 


Detaches an application from a database. Available in SQL. 

Syntax disconnect {{all I default} I dbhandle [, dbhandle] ...]}; 


Argument Description 

ALL I DEFAULT Either keyword detaches all open databases. 
dbhandle Previously declared database handle specifying a database to 

detach. 


Description DISCONNECT closes a specific database identified by a database handle or all 
databases, releases resources used by the attached database, zeroes database 
handles, commits the default transaction if the gpre -manual option is not in 
effect, and returns an error if any non-default transaction is not committed. 

Before using DISCONNECT, commit or roll back the transactions affecting the 
database to be detached. 

To reattach to a database closed with DISCONNECT, reopen it with a 
CONNECT statement. 

Examples The following embedded SQL statements close all databases: 

EXEC SQL 

DISCONNECT DEFAULT; 

EXEC SQL 

DISCONNECT ALL; 

The next embedded SQL statements close the databases identified by their 
handles: 

EXEC SQL 

DISCONNECT DBI; 

EXEC SQL 

DISCONNECT DBI, DB2; 

See Also COMMIT, CONNECT, ROLLBACK, SET DATABASE 
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DROP DATABASE 


DROP DATABASE 



Deletes the currently attached database. Available in isql. 

Syntax 

DROP DATABASE; 

Description 

DROP DATABASE deletes the currently attached database, including any asso¬ 
ciated secondary, shadow, and log files. Dropping a database deletes any data it 
contains. 

A database can be dropped by its creator, the SYSDBA user, and any users with 
operating system root privileges. 

Exampie 

The following isql statement deletes the current database: 

DROP DATABASE; 

See Aiso 

ALTER DATABASE, CREATE DATABASE 


DROP DOMAIN 



Deletes a domain from a database. Available in SQL, DSQL, and isql. 

Syntax 

Important 

DROP DOMAIN name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of an existing domain. 

Description 

DRQP DQMAIN removes an existing domain definition from a database. 

If a domain is currently used in any column definition in the database, the 

DRQP operation fails. To prevent failure, use ALTER TABLE to delete the col¬ 
umns based on the domain before executing DRQP DQMAIN. 

A domain may be dropped by its creator, the SYSDBA, and any users with oper¬ 
ating system root privileges. 
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DROP EXCEPTION 


Example 

The following isql statement deletes a domain: 

DROP DOMAIN COUNTRYNAME; 

See Also 

ALTER DOMAIN, ALTER TABLE, CREATE DOMAIN 


DROP EXCEPnON 



Deletes an exception from a database. Available in DSQL and isql. 

Syntax 

DROP EXCEPTION name 

Argument Description 

name Name of an existing exception message. 

Description 

DROP EXCEPTION removes an exception from a database. 

Exceptions used in existing procedures and triggers carmot be dropped. 

Tip 

In isql, SHOW EXCEPTION displays a list of exceptions' dependencies, the 
procedures and triggers that use the exceptions. 

An exception can be dropped by its creator, the SYSDBA user, and any user with 
operating system root privileges. 

Example 

This isql statement drops an exception: 

DROP EXCEPTION UNKNOWN_EMP_ID; 

See Also 

ALTER EXCEPTION, ALTER PROCEDURE, ALTER TRIGGER, GREATE 
EXGEPTION, GREATE PROGEDURE, GREATE TRIGGER 


DROP EXTERNAL FUNCTION 


Syntax 

Important 

Removes a user-defined frmction (UDE) declaration from a database. Available 
in SQL, DSQL, and isql. 

DROP EXTERNAL FUNCTION name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 
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DROP FILTER 



Argument Description 

name Name of an existing UDF. 

Description 

DROP EXTERNAL EUNCTION deletes a UDE declaration from a database. 
Dropping a UDE declaration from a database does not remove it from the corre¬ 
sponding UDE library, but it does make the UDE inaccessible from the database. 
Once the definition is dropped, any applications that depend on the UDE will 
return rim-time errors. 

Important 

A UDE can be dropped by its declarer, the SYSDBA user, or any users with oper¬ 
ating system root privileges. 

UDEs are not available for databases on NetWare servers. If a UDE is acci¬ 
dentally declared for a database on a NetWare server, DROP EXTERNAL 
EUNCTION should be used to remove the declaration. 

Exampie 

This isql statement drops a UDE: 

DROP EXTERNAL FUNCTION TOPS; 

See Aiso 

DECLARE EXTERNAL EUNCTION 


DROP FILTER 



Removes a BLOB filter declaration from a database. Available in SQL, DSQL, 
and isql. 

Syntax 

Important 

DROP FILTER name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of an existing BLOB filter. 

Description 

DRQP EILTER removes a BLQB filter declaration from a database. Dropping a 
BLQB filter declaration from a database does not remove it from the correspond¬ 
ing BLQB fUter library, but it does make the fUter inaccessible from the database. 
Once the definition is dropped, any applications that depend on the filter will 
return rim-time errors. 
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DROP INDEX 


Important 

DROP FILTER fails and returns an error if any processes are using the filter. 

A filter can be dropped by its creator, the SYSDBA user, or any user with operat¬ 
ing system root privileges. 

BLOB filters are not available for databases on NetWare servers. If a BLOB 
filter is accidentally declared for a database on a NetWare server, DROP 

FILTER should be used to remove the declaration. 

Example 

This isql statement drops a BLOB filter: 

DROP FILTER DESC_FILTER; 

See Also 

DECLARE FILTER 


DROP INDEX 



Removes an index from a database. Available in SQL, DSQL, and isql. 

Syntax 

Important 

DROP INDEX name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of an existing index. 

Description 

DRQP INDEX removes a user-defined index from a database. 

An index can be dropped by its creator, the SYSDBA user, or any user with oper¬ 
ating system root privileges. 

Important 

System-defined indexes, such as those for UNIQUE, PRIMARY KEY, and 
FQREIGN KEY integrity constraints, carmot be dropped. 

An index in use is not dropped until it is no longer in use. 

Example 

The following isql statement deletes an index: 

DROP INDEX MINSALX; 

See Also 

ALTER INDEX, CREATE INDEX 

For more information about integrity constraints and system-defined indexes, 
see the Data Definition Guide. 
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DROP PROCEDURE 


DROP PROCEDURE 


Deletes an existing stored procedure from a database. Available in DSQL, and 

isql. 

Syntax drop procedure name 


Argument 

Description 

name 

Name of an existing stored procedure. 


Description DROP PROCEDURE removes an existing stored procedure definition from a 
database. 

Procedures used by other procedures, triggers, or views carmot be dropped. Pro¬ 
cedures currently in use carmot be dropped. 

Tip In isql, SHOW PROCEDURE displays a list of procedures' dependencies, the 

procedures, triggers, exceptions, and tables that use the procedures. 

A procedure can be dropped by its creator, the SYSDBA user, or any user with 
operating system root privileges. 


Exampie The following isql statement deletes a procedure: 

DROP PROCEDURE GET_EMP_PROJ; 


See Aiso ALTER PROCEDURE, CREATE PROCEDURE, EXECUTE PROCEDURE 


DROP SHADOW 

Deletes a shadow from a database. Available in SQL, DSQL, and isql. 

Syntax drop shadow set_num; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

set_num 

Positive integer to identify an existing shadow set. 
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DROP TABLE 


Description 

DROP SHADOW deletes a shadow set and detaches from the shadowing pro¬ 
cess. The isql SHOW DATABASE command can be used to see shadow set num¬ 
bers for a database. 

A shadow can be dropped by its creator, the SYSDBA user, or any user with 
operating system root privileges. 

Exampie 

The following isql statement deletes a shadow set from its database: 

DROP SHADOW 1; 

See Aiso 

CREATE SHADOW 


DROP TABLE 



Removes a table from a database. Available in SQL, DSQL, and isql. 

Syntax 

Important 

DROP TABLE name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of an existing tabie. 

Description 

DRQP TABLE removes a table's data, metadata, and indexes from a database. It 
also drops any triggers that reference the table. 

A table referenced in an SQL expression, a view, integrity constraint, or stored 
procedure carmot be dropped. A table used by an active transaction is not 
dropped until it is free. 

Note 

When used to drop an external table, DRQP TABLE only removes the table 
definition from the database. The external file is not deleted. 

A table can be dropped by its creator, the SYSDBA user, or any user with operat¬ 
ing system root privileges. 

Exampie 

The following embedded SQL statement drops a table: 

EXEC SQL 

DROP TABLE COUNTRY; 

See Aiso 

ALTER TABLE, CREATE TABLE 
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DROP TRIGGER 


DROP TRIGGER 


Deletes an existing user-defined trigger from a database. Available in DSQL and 

isql. 

Syntax drop trigger name 


Argument 

Description 

name 

Name of an existing trigger. 


Description DROP TRIGGER removes a user-defined trigger definition from the database. 

System-defined triggers, such as those created for CHECK constraints, carmot be 
dropped. Use ALTER TABLE to drop the CHECK clause that defines the trigger. 

Triggers used by an active transaction carmot be dropped rmtil the transaction is 
terminated. 

A trigger can be dropped by its creator, the SYSDBA user, or any user with oper¬ 
ating system root privileges. 

Tip To inactivate a trigger temporarily, use ALTER TRIGGER and specify 
INACTIVE in the header. 


Example The following isql statement drops a trigger: 

DROP TRIGGER POST_NEW_ORDER; 

See Also ALTER TRIGGER, CREATE TRIGGER 


DROP VIEW 

Removes a view definition from the database. Available in SQL, DSQL, and isql. 

Syntax drop view name; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

name 

Name of an existing view definition to drop. 
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END DECLARE SECTION 


Description 

DROP VIEW enables a view's creator to remove a view definition from the data¬ 
base if the view is not used in another view, stored procedure, or CHECK con¬ 
straint definition. 

A view can be dropped by its creator, the SYSDBA user, or any user with operat¬ 
ing system root privileges. 

Exampie 

The following isql statement removes a view definition: 

DROP VIEW PHONE_LIST; 

See Aiso 

CREATE VIEW 


END DECLARE SEaiON 



Identifies the end of a host-language variable declaration section. Available in 
SQL. 

Syntax 

END DECLARE SECTION; 

Description 

END DECLARE SECTION is used in embedded SQL applications to identify the 
end of host-language variable declarations for variables that will be used in sub¬ 
sequent SQL statements. 

Exampie 

The following embedded SQL statements declare a section, and single host- 
language variable: 

EXEC SQL 

BEGIN DECLARE SECTION; 

BASED_ON EMPLOYEE.SALARY salary; 

EXEC SQL 

END DECLARE SECTION; 

See Aiso 

BASED ON, BEGIN DECLARE SECTION 


EVENT INIT 


Syntax 

Registers interest in one or more events with the InterBase event manager. Avail¬ 
able in SQL. 

EVENT INIT request_name l<dbhandle>] 

l{"<string>" \ :<variable> [, ”<string>" \ :<variable> ...]); 
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EVENT WAIT 


Argument 

Description 

request_name 

Application event handle. 

<dbhandle> 

Specifies the database to examine for occurrences of the events. 

If omitted, <dbhandle> defaults to the database named in the 
most recent SET DATABASE statement. 

"<string>" 

Unique name identifying an event associated with event_name. 

:<variable> 

Host-language character array containing a list of event names 
to associate with. 


Description EVENT INIT is the first step in the InterBase two-part S5mchronous event 
mechanism: 

1. EVENT INIT registers an application's interest in an event. 

2. EVENT WAIT causes the application to wait until notified of the event's 
occurrence. 

EVENT INIT registers an application's interest in a list of events in parentheses. 
The list should correspond to events posted by stored procedures or triggers in 
the database. If an application registers interest in multiple events with a single 
EVENT INIT, then when one of those events occurs, the application must deter¬ 
mine which event occurred. 

Events are posted by a POST_EVENT call within a stored procedure or trigger. 

The event manager keeps track of events of interest. At commit time, when an 
event occurs, the event manager notifies interested applications. 

Example The following embedded SQL statement registers interest in an event: 

EXEC SQL 

EVENT INIT ORDER_WAIT EMPDB ("new_order"); 

See Also CREATE PROCEDURE, CREATE TRIGGER, EVENT WAIT, SET DATABASE 
For more information about events, see the Programmer's Guide. 


EVENT WAIT 

Gauses an application to wait until notified of an event's occurrence. Available 
in SQL. 

Syntax event wait request_name; 
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EXECUTE 


Argument 

Description 

request_name 

Application event handle declared in a previous EVENT INIT 
statement. 


Description EVENT WAIT is the second step in the InterBase two-part S5mchronous event 
mechanism. After a program registers interest in an event, EVENT WAIT causes 
the process rurming the application to sleep rmtil the event of interest occurs. 

Exampies The following embedded SQL statements register an application event name 

and indicate the program is ready to receive notification when the event occurs: 

EXEC SQL 

EVENT INIT ORDER_WAIT EMPDB ("new_order"); 

EXEC SQL 

EVENT WAIT ORDER_WAIT; 


See Aiso EVENT INIT 

For more information about events, see the Programmer's Guide. 


EXECUTE 


Executes a previously prepared dynamic SQL (DSQL) statement. Available in 
SQL. 

Syntax execute [transaction transaction] statement 

[USING SQL DESCRIPTOR xsqlda] [INTO SQL DESCRIPTOR xsqlda] ; 


Argument 

Description 

TRANSACTION 

transaction 

Specifies the transaction under which execution occurs. 

statement 

Alias of a previously prepared statement to execute. 

USING SQL 
DESCRIPTOR 

Specifies that values corresponding to the prepared statement's 
parameters should be taken from the specified XSQLDA. 

INTO SQL 
DESCRIPTOR 

Specifies that return values from the executed statement should 
be stored in the specified XSQLDA. 

xsqlda 

XSQLDA host-language variable. 
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EXECUTE 


Description EXECUTE carries out a previously prepared DSQL statement. It is one of a 
group of statements that process DSQL statements. 


Statement Purpose 

PREPARE Readies a DSQL statement for execution. 

DESCRIBE Fills in the XSQLDA with information about the statement. 

EXECUTE Executes a previously prepared statement. 

EXECUTE Prepares a DSQL statement, executes it once, and discards it. 

IMMEDIATE 

Before a statement can be executed, it must be prepared using the PREPARE 
statement. The statement can be any SQL data definition, manipulation, or 
transaction management statement. Once it is prepared, a statement can be exe¬ 
cuted any number of times. 

The TRANSACTIQN clause can be used in SQL applications running multiple, 
simultaneous transactions to specify which transaction controls the EXECUTE 
operation. 

USING DESCRIPTQR enables EXECUTE to extract a statement's parameters 
from an XSQLDA structure previously loaded with values by the application. It 
need only be used for statements that have d5mamic parameters. 

INTQ DESCRIPTQR enables EXECUTE to store return values from statement 
execution in a specified XSQLDA structure for application retrieval. It need only 
be used for DSQL statements that return values. 

Note If an EXECUTE statement provides both a USING DESCRIPTQR clause 
and an INTQ DESCRIPTQR clause, then two XSQLDA structures must be 
provided. 

Example The following embedded SQL statement executes a previously prepared DSQL 
statement: 

EXEC SQL 

EXECUTE DOUBLE_SMALL_BUDGET; 

The next embedded SQL statement executes a previously prepared statement 
with parameters stored in an XSQLDA: 

EXEC SQL 

EXECUTE Q USING DESCRIPTOR xsqlda; 

The following embedded SQL statement executes a previously prepared state¬ 
ment with parameters in one XSQLDA, and produces results stored in a second 
XSQLDA: 
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EXECUTE IMMEDIATE 


EXEC SQL 

EXECUTE Q USING DESCRIPTOR xsqlda_l INTO DESCRIPTOR xsqlda_2; 

See Also DESCRIBE, EXECUTE IMMEDIATE, PREPARE 

Eor more information about DSQL programming and the XSQLDA, see the Pro¬ 
grammer's Guide. 


EXECUTE IMMEDIATE 

Prepares a d5mamic SQL (DSQL) statement, executes it once, and discards it. 
Available in SQL. 

Syntax execute immediate [TRANSACTION transaction] 

{:<variable> \ "string"} [USING SQL DESCRIPTOR xsqlda]} 


Argument 

transaction 

transaction 

:<variable> 

"string’ 

USING SQL 

DESCRIPTOR 

xsqlda 


Description 

Specifies the transaction under which execution occurs. 

Host variable containing the SQL statement to execute. 

A string literal containing the SQL statement to execute. 
Specifies that values corresponding to the statement’s parame¬ 
ters should be taken from the specified XSQLDA. 

XSQLDA host-language variable. 


Description EXECUTE IMMEDIATE prepares a DSQL statement stored in a host-language 
variable or in a literal string, executes it once, and discards it. To prepare and 
execute a DSQL statement for repeated use, use PREPARE and EXECUTE 
instead of EXECUTE IMMEDIATE. 

The TRANSACTIQN clause can be used in SQL applications rurming multiple, 
simultaneous transactions to specify which transaction controls the EXECUTE 
IMMEDIATE operation. 

The SQL statement to execute must be stored in a host variable or be a string 
literal. It can contain any SQL data definition statement or data manipulation 
statement that does not return output. 

USING DESCRIPTQR enables EXECUTE IMMEDIATE to extract the values of a 
a statement's parameters from an XSQLDA structure previously loaded with 
appropriate values. 
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EXECUTE PROCEDURE 


Example The following embedded SQL statement prepares and executes a statement in a 

host variable: 

EXEC SQL 

EXECUTE IMMEDIATE :insert_date; 

See Also DESCRIBE, EXECUTE IMMEDIATE, PREPARE 

Eor more information about DSQL programming and the XSQLDA, see the Pro¬ 
grammer's Guide. 


EXECUTE PROCEDURE 

Calls a stored procedure. Available in SQL, DSQL, and isql. 

Syntax SQL form: 

EXECUTE PROCEDURE [TRANSACTION transaction] 
name [:param [[INDICATOR]:indicator]] 

[, -.param [[ INDICATOR] : indicator] ...] 
[RETURNING_VALUES :param [[INDICATOR]:indicator] 
[, -.param [[ INDICATOR] : indicator] ...]]; 

DSQL form: 

EXECUTE PROCEDURE name [param [, param ...]] 
[RETURNING_VALUES param [, param ...]] 

isql form: 

EXECUTE PROCEDURE name [param [, param ...]] 


Argument Description 

TRANSACTION Specifies the transaction under which execution occurs. 

transaction 

name Name of an existing stored procedure in the database. 

param Input or output parameter. Can be a host variable or a constant. 

RETURNING_VALUES Host variable which takes the values of an output parameter. 

; param 


[INDICATOR] Host variable for indicating NULL or unknown values. 

■.indicator 


Description EXECUTE PRQCEDURE calls the specified stored procedure. If the procedure 
requires input parameters, they are passed as host-language variables or as con¬ 
stants. If a procedure returns output parameters to an SQL program, host vari¬ 
ables must be supplied in the RETURN1NG_VALUES clause to hold the values 
returned. 
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FETCH 


Note 

Examples 

See Also 

FETCH 

Syntax 


In isql, do not use the RETURN clause or specify output parameters, isql will 
automatically display return values. 

In DSQL, an EXECUTE PROCEDURE statement requires an input descrip¬ 
tor area if it has input parameters and an output descriptor area if it has 
output parameters. 

In embedded SQL, input parameters and return values may have associated 
indicator variables for tracking NULL values. Indicator variables are integer val¬ 
ues that indicate imknown or NULL values of return values. 

An indicator variable that is less than zero indicates that the parameter is 
unknown or NULL. An indicator variable that is zero or greater indicates that 
the associated parameter is known and not NULL. 

The following embedded SQL statement demonstrates how the executable pro¬ 
cedure, DEPT_BUDGET, is called from embedded SQL with literal parameters: 

EXEC SQL 

EXECUTE PROCEDURE DEPT_BUDGET 100 RETURNING_VALUES :sumb; 

The next embedded SQL statement calls the same procedure using a host vari¬ 
able instead of a literal as the input parameter: 

EXEC SQL 

EXECUTE PROCEDURE DEPT_BUDGET :rdno RETURNING_VALUES :sumb; 

ALTER PRQCEDURE, CREATE PRQCEDURE, DRQP PRQCEDURE 
Lor more information about indicator variables, see the Programmer's Guide. 


Retrieves the next available row from the active set of an opened cursor. Avail¬ 
able in SQL and DSQL. 

SQL form: 

FETCH cursor 

[INTO -.hostvar [[INDICATOR] : indvar] 

[, -.hostvar [[INDICATOR] -.indvar] ...]]; 

DSQL form: 

FETCH cursor {INTO | USING} SQL DESCRIPTOR xsqlda 

Blob form: 

See FETCH (BLOB). 
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FETCH 


Argument Description 

cursor Name of the opened cursor from which to fetch rows. 

■.hostvar A host-language variable for holding values retrieved with the 

FETCH. 

• Optional if FETCH gets rows for DELETE or UPDATE. 

• Required if row is displayed before DELETE or UPDATE. 

■.indvar Indicator variable for reporting that a column contains an 

unknown or NULL value. 

[INTO I USING] SQL Specifies that values should be returned in the specified 

DESCRIPTOR XSQLDA. 

xsqlda XSQLDA host-language variable. 

Description FETCH retrieves one row at a time into a program from the active set of a cursor. 

The first FETCH operates on the first row of the active set. Subsequent FETCH 
statements advance the cursor sequentially through the active set one row at a 
time until no more rows are found and SQLCODE is set to 100. 

A cursor is a one-way pointer into the ordered set of rows retrieved by the select 
expression in the DECLARE CURSOR statement. A cursor enables sequential 
access to retrieved rows. There are four related cursor statements: 


Stage Statement 

Purpose 

1 

DECLARE 

CURSOR 

Declare the cursor. The SELECT statement determines rows 
retrieved for the cursor. 

2 

OPEN 

Retrieve the rows specified for retrieval with DECLARE 

CURSOR. The resulting rows become the cursor’s active set. 

3 

FETCH 

Retrieve the current row from the active set, starting with the first 
row. Subsequent FETCH statements advance the cursor through 
the set. 

4 

CLOSE 

Close the cursor and release system resources. 


The number, size, data t 5 q)e, and order of columns in a FETCH must be the same 
as those listed in the query expression of its matching DECLARE CURSOR state¬ 
ment. If they are not, the wrong values can be assigned. 


Examples The following embedded SQL statement fetches a column from the active set of 
a cursor: 

EXEC SQL 

FETCH PROJ_CNT INTO :department, :hcnt; 


94 


Language Reference 








FETCH (BLOB) 


See Also CLOSE, DECLARE CURSOR, DELETE, EETCH (BLOB), OPEN 

Eor more information about cursors and XSQLDA, see the Programmer's Guide. 


FETCH (BLOB) 


Retrieves the next available segment of a BLOB column and places it in the spec¬ 
ified local buffer. Available in SQL. 

Syntax FETCH cursor INTO 

[: <buffer> [[INDICATOR] : segment_length \; 


Argument 

Description 

cursor 

Name of an open BLOB cursor from which to retrieve segments. 

:<buffer> 

Host-language variable for holding segments fetched from the 
BLOB column. User must declare the buffer before fetching seg¬ 
ments into it. 

INDICATOR 

Optional keyword indicating that a host-language variable for 
indicating the number of bytes returned by the FETCH follows. 

■.segmentjength 

Host-language variable used to indicate he number of bytes 
returned by the FETCH. 


Description EETCH retrieves the next segment from a BLOB and places it into the specified 
buffer. 

The host variable, segment Jength, indicates the number of bytes fetched. This is 
useful when the number of bytes fetched is smaller than the host variable, for 
example, when fetching the last portion of a BLOB. 

EETCH can return two SQLCODE values: 

• SQLCODE = 100 indicates that there are no more BLOB segments to 
retrieve. 

• SQLCODE = 101 indicates that a partial segment was retrieved and 
placed in the local buffer variable. 

Note To ensure that a host variable buffer is large enough to hold a BLOB seg¬ 
ment buffer during EETCH operations, use the SEGMENT option of the 
BASED ON statement. 


Example The following code, from an embedded SQL application, performs a BLQB 
EETCH: 
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GENJD() 


See Also 


GENJDO 

Syntax 


Description 


lile (SQLCODE != 100) 
EXEC SQL 

OPEN BLOB_CUR USING 
EXEC SQL 

FETCH BLOB_CUR INTO 


:blob_id; 

:blob_segment 


while (SQLCODE !=100 I I SQLCODE == 101) 


blob_segment{blob_seg_len + 1] = '\0'; 

printf("%*.*s",blob_seg_len,blob_seg_len,blob_segment); 

blob_segment{blob_seg_len +1] = ' 

EXEC SQL 

FETCH BLOB_CUR INTO :blob_segment :blob_seg_len; 


BASED ON, CLOSE (BLOB), DECLARE CURSOR (BLOB), INSERT CURSOR 
(BLOB), OPEN (BLOB) 


Produces a system-generated integer value. Available in SQL, DSQL, and isql. 


GEN_ID (generatoi 

-, step) 

Argument 

Description 

generator 

Name of an existing generator. 

step 

Integer or expression specifying the increment for increasing or 
decreasing the current generator vaiue. Vaiues can range from 
.(231) to 231 ..| 


The GEN_ID() frmction: 

1. Increments the current value of the specified generator by step. 

2. Returns the new value of the specified generator. 

GEN_ID() is useful for automatically producing unique values that can be 
inserted into a UNIQUE or PRIMARY KEY column. To insert a generated num¬ 
ber in a column, write a trigger, procedure, or SQL statement that calls 
GENJD(). 
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GRANT 


Note 

A generator is initially created with CREATE GENERATOR. By default, the 
value of a generator begins at zero. It can be set to a different value with 

SET GENERATOR. 

Examples 

The following isql trigger definition includes a call to GEN_1D(): 

SET TERM !! ; 

CREATE TRIGGER CREATE_EMPNO FOR EMPLOYEES 

BEFORE INSERT 

POSITION 0 

AS BEGIN 

NEW.EMPNO = GEN_ID (EMPNO_GEN, 1); 

END 

SET TERM ; !! 

The first time the trigger fires, NEW.EMPNO is set to 1. The next time, it is set to 
2, and so on. 

See Also 

GREATE GENERATOR, SET GENERATOR 


GRANT 



Assigns privileges to users for specified database objects. Available in SQL, 
DSQL, and isql. 

Syntax 

GRANT { 

{ALL [PRIVILEGES] | SELECT | DELETE | INSERT 

1 UPDATE [ (col [, col ...])]} 

ON [TABLE] {tablename | viewname} 

TO {<object> 1 <userlist>] 

1 EXECUTE ON PROCEDURE procname 

TO {<object> 1 <userlist>] 

]; 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<object> = PROCEDURE procname | TRIGGER trigname \ VIEW viewname 

1 [USER] username \ PUBLIC [, <object>] 

<userlist> = [USER] username [, [USER] username ...] 

[WITH GRANT OPTION] 
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GRANT 


Description 


Argument 

Description 

col 

Column to which the granted privileges apply. 

tablename 

Name of an existing table for which granted privileges apply. 

viewname 

Name of an existing view for which granted privileges apply. 

<object> 

Name of a user or an existing database object to which privileges 
are to be granted. 

<userlist> 

A list of users to whom privileges are to be granted. 

WITH GRANT 
OPTION 

Passes GRANT authority for privileges listed in the GRANT 
statement to <userlist>. 


GRANT assigns privileges for database objects to users or other database 
objects. When an object is first created, only its creator has privileges to it, and 
only its creator can GRANT privileges for it to other users or objects. 

To access a table or view, a user or object needs SELEGT, INSERT, UPDATE, or 
DELETE privileges for that table or view. SELEGT, INSERT, UPDATE, and 
DELETE privileges may be assigned as a rmit with ALL. 

To call a stored procedure in an application, a user or object needs EXEGUTE 
privilege for it. 

Users can be given permission to grant privileges to other users by providing a 
<userlist> that includes the WITH GRANT OPTION. Users can only grant to 
others the privileges that they, themselves, are assigned. 

Privileges may be assigned to all users by specifying PUBLIG in place of a list of 
user names. Specifying PUBLIG grants privileges only to users, not to database 
objects. 

The following table summarizes available privileges: 


Table 2-9: SQL Privileges 


Privilege 

Enables users to ... 

ALL 

Perform SELECT, DELETE, INSERT, UPDATE, and EXECUTE. 

SELECT 

Retrieve rows from a table or view. 

DELETE 

Eliminate rows from a table or view. 

INSERT 

Store new rows in a table or view. 

UPDATE 

Change the current value of one or more columns in a table or 
view. Can be restricted to a specified subset of columns. 

EXECUTE 

Execute a stored procedure. 
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INSERT 


Examples 

See Also 

INSERT 

Syntax 

Important 


Privileges can only be removed by the user who assigned them by using 
REVOKE. If ALL privileges are assigned, then ALL privileges must be revoked. 
If privileges are granted to PUBLIC, they may only be removed for PUBLIC. 

The following isql statement grants SELECT and DELETE privileges to a user. 
The WITH GRANT OPTION gives the user GRANT authority. 

GRANT SELECT, DELETE ON COUNTRY TO CHLOE WITH GRANT OPTION; 

The next embedded SQL statement, from an embedded program, grants 
SELEGT and UPDATE privileges to a procedure for a table: 

EXEC SQL 

GRANT SELECT, UPDATE ON JOB TO PROCEDURE GET_EMP_PROJ; 

This embedded SQL statement grants EXEGUTE privileges for a procedure to 
another procedure, and to a user: 

EXEC SQL 

GRANT EXECUTE ON PROCEDURE GET_EMP_PROJ 
TO PROCEDURE ADD_EMP_PROJ, LUIS; 

REVQKE 

Eor more information about privileges, see the Data Definition Guide. 


Adds one or more new rows to a specified table. Available in SQL, DSQL, and 

isql. 

INSERT [TRANSACTION transaction] INTO <object> [{col [, col ...])] 
{VALUES (<val> [, <val> ...]) I <select_expr>}} 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in G and G++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<object> = tablename | viewname 

:variable \ <constant> \ <expr> 

I <function> \ udf {[<val> [, <val> ...]]) 

I NULL I USER I RDB$DB_KEY | ? 

} [COLLATE collation] 
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INSERT 


Note In SQL and isql, <val> cannot be a parameter placeholder (?). In DSQL and 

isql <val> cannot be a variable. The COLLATE clause cannot be used with 
BLOB values. 

<constant> = num \ "string" | charsetname "string" 

<expr> = A valid SQL expression that results in a single column value. 
<function> = { 

CAST (<val> AS <datatype>) 

I UPPER (<val>) 

I GEN_ID {generator, <val>) 


<select_expr> = A SELECT returning zero or more rows and where the 
number of columns in each row is the same as the number of items 
to be inserted. 


Argument 

Description 

TRANSACTION 

transaction 

Name of the transaction that controls the execution of the 

INSERT. 

INTO <object> 

Name of an existing table or view Into which to insert data. 

col 

Name of an existing column in a table or view Into which to Insert 
values. 

VALUES 

{<val> [, <val >...]) 

Lists values to insert into the table or view. Values must be listed 
in the same order as the target columns. 

<select_expr> 

Query that returns row values to Insert Into target columns. 


Description INSERT stores one or more new rows of data in an existing table or view. 

INSERT is one of the database privileges controlled by the GRANT and 
REVOKE statements. 

Values are inserted into a row in column order unless an optional list of target 
columns is provided. If the target list of columns is a subset of available col¬ 
umns, default or NULL values are automatically stored in all xmlisted columns. 

If the optional list of target columns is omitted, the VALUES clause must provide 
values to insert into all columns in the table. 

To insert a single row of data, the VALUES clause should include a specific list of 
values to insert. 

To insert multiple rows of data, specify a <select_expr> that retrieves existing 
data from another table to insert into this one. The selected columns must corre¬ 
spond to the columns listed for insert. 

Caution It is legal to select from the same table into which insertions are made, but 
this practice is not advised because it may result in infinite row insertions. 
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INSERT CURSOR (BLOB) 


The TRANSACTION clause can be used in multiple transaction SQL applica¬ 
tions to specify which transaction controls the INSERT operation. The 
TRANSACTION clause is not available in DSQL or isql. 

Examples The following statement, from an embedded SQL application, adds a row to a 
table, assigning values from host-language variables to two columns: 

EXEC SQL 

INSERT INTO EMPLOYEE_PROJECT (EMP_NO, PROJ_ID) VALUES (:emp_no, 
:proj_id.) ; 

The next isql statement specifies values to insert into a table with a SELECT 
statement: 

INSERT INTO PROJECTS 

SELECT * FROM NEW_PROJECTS 

WHERE NEW_PROJECTS.START_DATE > "6-JUN-I994"; 

See Also GRANT, REVOKE, SET TRANSACTION, UPDATE 


INSERT CURSOR (BLOB) 

Inserts data into a BLOB cursor in units of a BLOB segment-length or less in size. 
Available in SQL. 

Syntax insert cursor cursor 

VALUES (-.buffer [INDICATOR] ibufferlen) ; 


Argument 

Description 

cursor 

Name of the BLOB cursor. 

VALUES 

Clause containing the name and length of the buffer variable to 
insert. 

■.buffer 

Name of host-variable buffer containing information to insert. 

INDICATOR 

Indicates that the length of data placed in the buffer follows. 

-.bufferten 

Length, in bytes, of the buffer to insert. 


Description INSERT CURSOR writes BLOB data into a column. Data is written in units equal 
to or less than the segment size for the BLOB. Before inserting data into a BLOB 
cursor: 

• Declare a local variable, bujfer, to contain the data to be inserted. 

• Declare the length of the variable, bujferlen. 
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MAXO 


Important 

Example 

See Also 

MAXO 

Syntax 

Description 

Example 


• Declare a BLOB cursor for INSERT and open it. 

Each INSERT into the BLOB column inserts the current contents of buffer. 
Between statements fill buffer with new data. Repeat the INSERT imtil each exist¬ 
ing buffer is inserted into the BLOB. 

INSERT CURSOR requires the INSERT privilege, a table privilege con¬ 
trolled by the GRANT and REVOKE statements. 

The following embedded SQL statement shows an insert into the BLOB cursor: 

EXEC SQL 

INSERT CURSOR BC VALUES (:line INDICATOR :len); 

CLOSE (BLOB), DECLARE CURSOR (BLOB), EETCH (BLOB), OPEN (BLOB) 


Retrieves the maximum value in a column. Available in SQL, DSQL, and isql. 


MAX ([ALL] <val> 

1 DISTINCT <val>) 

Argument 

Description 

ALL 

DISTINCT 

<val> 

Searches all values in a column. 

Eliminates duplicate values before finding the largest. 

A column, constant, host-language variable, expression, non¬ 
aggregate function, or UDF. 


MAX() is an aggregate function that returns the largest value in a specified col¬ 
umn, excluding NULL values. If the number of qualifying rows is zero, MAX() 
returns a NULL value. 

When MAX() is used on a CHAR, VARCHAR, or BLQB text column, the largest 
value returned varies depending on the character set and collation in use for the 
column. A default character set can be specified for an entire database with the 
DEEAULT CHARACTER SET clause in CREATE DATABASE, or specified at the 
column level with the CQLLATE clause in CREATE TABLE. 

The following embedded SQL statement demonstrates the use of SUM(), AVG(), 
MIN(), and MAX(): 

EXEC SQL 

SELECT SUM (BUDGET), AVG (BUDGET), MIN (BUDGET), MAX (BUDGET) 

FROM DEPARTMENT 
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MINO 


See Also 

MINO 

Syntax 

Description 

Example 

See Also 


WHERE HEAD_DEPT = :head_dept 

INTO :tot_budget, :avg_budget, :min_budget, :max_budget; 

AVG(), COUNTO, CREATE DATABASE, CREATE TABLE, MIN(), SUM{) 


Retrieves the minimum value in a column. Available in SQL, DSQL, and isql. 


MIN ([ALL] <val> 

1 DISTINCT <val>) 

Argument 

Description 

ALL 

DISTINCT 

<val> 

Searches all values in a column. 

Eliminates duplicate values before finding the smallest. 

A column, constant, host-language variable, expression, non¬ 
aggregate function, or UDF. 


MIN() is an aggregate function that returns the smallest value in a specified col¬ 
umn, excluding NULL values. If the number of qualifying rows is zero, MIN() 
returns a NULL value. 

When MIN() is used on a CHAR, VARCHAR, or BLOB text column, the smallest 
value returned varies depending on the character set and collation in use for the 
column. A default character set can be specified for an entire database with the 
DELAULT CHARACTER SET clause in CREATE DATABASE, or specified at the 
column level with the COLLATE clause in CREATE TABLE. 

The following embedded SQL statement demonstrates the use of SUM(), AVG(), 
MINO, and MAX(): 

EXEC SQL 

SELECT SUM (BUDGET), AVG (BUDGET), MIN (BUDGET), MAX (BUDGET) 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :head_dept 

INTO :tot_budget, :avg_budget, :min_budget, :max_budget; 

AVG(), COUNTO, CREATE DATABASE, CREATE TABLE, MAXO, SUMO 
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OPEN 


Retrieve specified rows from a cursor declaration. Available in SQL and DSQL. 
Syntax SQL form: 

OPEN [TRANSACTION transaction] cursor; 

DSQL form: 

OPEN [TRANSACTION transaction] cursor [USING SQL DESCRIPTOR xsqlda] 

Blob form: 

See OPEN (BLOB). 


Argument Description 

transaction Name of the transaction that controls execution of OPEN. 

transaction 

cursor Name of a previously declared cursor to open. 

USING Passes the values corresponding to the prepared statement’s 

DESCRIPTOR xsqlda parameters through the extended descriptor area (XSQLDA). 

Description QPEN evaluates the search condition specified in a cursor's DECLARE 

CURSQR statement. The selected rows become the active set for the cursor. 

A cursor is a one-way pointer into the ordered set of rows retrieved by the 
SELECT in a DECLARE CURSQR statement. It enables sequential access to 
retrieved rows in turn. There are four related cursor statements: 


Stage Statement 

Purpose 

1 

DECLARE 

CURSOR 

Declare the cursor. The SELECT statement determines rows 
retrieved for the cursor. 

2 

OPEN 

Retrieve the rows specified for retrieval with DECLARE 

CURSOR. The resulting rows become the cursor’s active set. 

3 

FETCH 

Retrieve the current row from the active set, starting with the first 
row. Subsequent FETCH statements advance the cursor through 
the set. 

4 

CLOSE 

Close the cursor and release system resources. 


Examples The following embedded SQL statement opens a cursor: 

EXEC SQL 
OPEN C; 


See Also CLQSE, DECLARE CURSQR, EETCH 
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OPEN (BLOB) 


Opens a previously declared BLOB cursor and prepares it for read or insert. 
Available in SQL. 

Syntax open [transaction name] cursor 

{INTO I USING} ■.blob_id} 


Argument 

Description 

TRANSACTION name Specifies the transaction under which the cursor is opened. 

Defauit: The default transaction. 

cursor 

Name of the BLOB cursor. 

INTO 1 USING 

Depending on BLOB cursor type, use one of these: 

• INTO: For INSERT BLOB. 

• USING: For READ BLOB. 

blobjd 

Identifier for the BLOB column. 


Description OPEN prepares a previously declared cursor for reading or inserting BLOB data. 

Depending on whether the DECLARE CURSOR statement declares a READ or 
INSERT BLOB cursor, OPEN obtains the value for BLOB ID differently: 

• For a READ BLOB, the blobjd comes from the outer TABLE cursor. 

• For an INSERT BLOB, the blobjd is returned by the system. 

Examples The following embedded SQL statements declare and open a BLQB cursor: 

EXEC SQL 

DECLARE BC CURSOR FOR 

INSERT BLOB PROJ_DESC INTO PRJOECT; 

EXEC SQL 

OPEN BC INTO :blob_id; 


See Also CLQSE (BLQB), DECLARE CURSQR (BLQB), FETCH (BLQB), INSERT 
CURSQR (BLQB) 


PREPARE 


Prepares a d5mamic SQL (DSQL) statement for execution. Available in SQL. 

Syntax prepare [transaction transaction] statement 

[INTO SQL DESCRIPTOR xsqlda] FROM {:<variable> | "string"}; 
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PREPARE 


Description 


Argument 

Description 

TRANSACTION 

transaction 

Name of the transaction under control of which the statement is 
executed. 

statement 

Establishes an alias for the prepared statement that can be used 
by subsequent DESCRIBE and EXCUTE statements. 

INTO xsqlda 

Specifies an XSQLDA to be filled in with the description of the 
select-list columns in the prepared statement. 

:<variable> \ "string’ 

DSQL statement to PREPARE. Can be a host-language variable 
or a string literal. 

PREPARE readies a DSQL statement for repeated execution by: 

• Checking the statement for syntax errors. 

• Determining data types of optionally specified d5mamic parameters. 

• Qptimizing statement execution. 

• Compiling the statement for execution by EXECUTE. 

PREPARE is part of a 
cution. 

group of statements that prepare DSQL statements for exe- 

Statement 

Purpose 

PREPARE 

Readies a DSQL statement for execution. 

DESCRIBE 

Fills in the XSQLDA with information about the statement. 

EXECUTE 

Executes a previously prepared statement. 

EXECUTE 

IMMEDIATE 

Prepares a DSQL statement, executes it once, and discards it. 


After a statement is prepared, it is available for execution as many times as nec¬ 
essary during the current session. To prepare and execute a statement only once, 
use EXECUTE IMMEDIATE. 


statement establishes a symbolic name for the actual DSQL statement to prepare. 
It is not declared as a host-language variable. Except for C programs, gpre does 
not distinguish between uppercase and lowercase in statement, treating "B" and 
"b" as the same character. Eor C programs, use the gpre -either_case switch to 
activate case sensitivity during preprocessing. 

If the optional INTO clause is used, PREPARE also fills in the extended SQL 
descriptor area (XSQLDA) with information about the data type, length, and 
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Note 

name of select-list columns in the prepared statement. This clause is useful only 
when the statement to prepare is a SELECT. 

The DESCRIBE statement can be used instead of the INTO clause to fill in 
the XSQLDA for a select list. 

The EROM clause specifies the actual DSQL statement to PREPARE. It can be a 
host-language variable, or a quoted-string literal. The DSQL statement to 
PREPARE can be any SQL data definition, data manipulation, or transaction- 
control statement. 

Examples 

The following embedded SQL statement prepares a DSQL statement from a 
host-variable statement. Because it uses the optional INTQ clause, the assump¬ 
tion is that the DSQL statement in the host variable is a SELECT. 

EXEC SQL 

PREPARE Q INTO xsqlda FROM :buf; 

Note 

The previous statement could also be prepared and described in the fol¬ 
lowing manner: 

EXEC SQL 

PREPARE Q FROM :buf; 

EXEC SQL 

DESCRIBE Q INTO SQL DESCRIPTOR xsqlda; 

See Also 

DESCRIBE, EXECUTE, EXECUTE IMMEDIATE 


REVOKE 



Withdraws privileges from users for specified database objects. Available in 

SQL, DSQL, and isql. 

Syntax 

REVOKE [GRANT OPTION FOR]{ 

{ALL [PRIVILEGES] | SELECT | DELETE | INSERT 

1 UPDATE [ (col [, col ...])]} 

ON [TABLE] {tablename | viewname) 

FROM {<Ojbject> 1 <userlist>} 

1 EXECUTE ON PROCEDURE procname 

FROM {<Ojbject> 1 <userlist>} 

]; 

Important 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 
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Description 


<object> = PROCEDURE procname \ TRIGGER trigname \ VIEW viewname 
I [USER] username \ PUBLIC [, <object>] 

<userlist> = [USER] username [, [USER] username ...] 


Argument 


Description 


GRANT OPTION FOR Removes grant authority for privileges listed in the REVOKE 
statement from <userlist>. Cannot be used with <obJect>. 
col Column to which the granted privileges apply. 

tablename Name of an existing table for which granted privileges apply. 

viewname Name of an existing view for which granted privileges apply. 

<object> Name of a user or an existing database object from which privi¬ 

leges are to be revoked. 

<userlist> A list of users from whom privileges are to be revoked. 


REVOKE removes privileges to access database objects from users or other data¬ 
base objects. Privileges are operations for which a user has authority. The follow¬ 
ing table defines SQL privileges: 


Table 2-10: SQL Privileges 


Privilege 

Removes a User’s Privilege to ... 

ALL 

Perform SELECT, DELETE, INSERT, UPDATE, and EXECUTE. 

SELECT 

Retrieve rows from a table or view. 

DELETE 

Remove rows from a table or view. 

INSERT 

Store new rows in a table or view. 

UPDATE 

Change the current value of one or more columns in a table or 
view. Can be restricted to a specified subset of columns. 

EXECUTE 

Execute a stored procedure. 


GRANT OPTION POR revokes a user's right to GRANT privileges to other 
users. 

The following limitations should be noted for REVOKE: 


Only the user who grants a privilege can revoke that privilege. 

A single user may be assigned the same privileges for a database object 
by any number of other users. A REVOKE issued by a user only removes 
privileges previously assigned by that particular user. 

Privileges granted to all users with PUBLIG can only be removed by 
revoking privileges from PUBLIG. 
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Examples The following isql statement takes the SELECT privilege away from a user for a 
table: 

REVOKE SELECT ON COUNTRY FROM MIREILLE; 

The following isql statement withdraws EXECUTE privileges for a procedure 
from another procedure and a user: 

REVOKE EXECUTE ON PROCEDURE GET_EMP_PROJ 
FROM PROCEDURE ADD_EMP_PROJ, LUIS; 

See Also GRANT 

Eor more information about privileges, see the Data Definition Guide. 


ROLLBACK 


Restores the database to its state prior to the start of the current transaction. 
Available in SQL, DSQL, and isql. 


Syntax rollback [transaction name] [WORK] [RELEASE]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

TRANSACTION name Specifies the transaction to roll back in a multiple-transaction 
application. Default: roll back the default transaction. 

WORK 

Optional word allowed for compatibility. 

RELEASE 

Detaches from all databases after ending the current transaction. 
SQL only. 


Description RQLLBACK undoes changes made to a database by the current transaction, then 
ends the transaction. It breaks the program's connection to the database and 
frees system resources. Use RELEASE in the last RQLLBACK to close all open 
databases. Wait imtil a program no longer needs the database to release system 
resources. 

The TRANSACTIQN clause can be used in multiple-transaction SQL applica¬ 
tions to specify which transaction to roll back. If omitted, the default transaction 
is rolled back. The TRANSACTIQN clause is not available in DSQL. 

Note RELEASE, available only in SQL, detaches from all databases after ending 
the current transaction. In effect, this option ends database processing. 
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SELECT 


Examples 

See Also 

SELEa 

Syntax 

Important 

Note 

no 


RELEASE is supported for backward compatibility with older versions of 
InterBase. The preferred method of detaching is with DISCONNECT. 

The following isql statement rolls back the default transaction: 

ROLLBACK; 

The next embedded SQL statement rolls back a named transaction: 

EXEC SQL 

ROLLBACK TRANSACTION MYTRANS; 

COMMIT, DISCONNECT 

Eor more information about controlling transactions, see the Programmer's Guide. 


Retrieves data from one or more tables. Available in SQL, DSQL, and isql. 

SELECT [TRANSACTION transaction] 

[DISTINCT I ALL] (* | <val> [, <val> ...]) 

[INTO :var [, :var ...]] 

FROM <tableref> [, <tableref> ...] 

[WHERE <search_condition>] 

[GROUP BY col [COLLATE collation] [, col [COLLATE collation] ...] 
[HAVING <search_condition>] 

[UNION <select_expr>] 

[PLAN <plan_expr>] 

[ORDER BY <order_list>] 

[FOR UPDATE [OF col [, col ...]]]; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. In isql, the 
INTQ clause cannot be specified. 

<val> = { 

col l<array_dim>] | -.variable 
I <constant> \ <expr> | <function> 

I udf {[<val> [, <val> ...]]) 

I NULL I USER I RDB$DB_KEY | ? 

} [COLLATE collation] [AS alias] 

In SQL and isql, <val> carmot be a parameter placeholder (?). In DSQL and 
isql, <val> cannot be a variable. The CQLLATE clause carmot be used with 
BLQB values. 
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<array_dlm> = [x:y [, x:y ...]] 

Note Outermost brackets, in bold, must be included when declaring arrays. 

<constant> = num \ "string" \ charsetname "string" 

<expr> = A valid SQL expression that results in a single value. 
<function> = { 

COUNT (* I [ALL] <val> \ DISTINCT <val>) 

I SUM {[ALL] <val> \ DISTINCT <val>) 

I AVG ([ALL] <val> \ DISTINCT <val>) 

I MAX ([ALL] <val> \ DISTINCT <val>) 

I MIN ([ALL] <val> \ DISTINCT <val>) 

I CAST (<val> AS <datatype>) 

I UPPER {<val>) 

I GEN_ID {generator, <val>) 


<tableref> = <joined_table> \ table \ view \ procedure 
[(<val> [, <val> ...])] [alias] 

<joined_table> = <tableref> <join_type> JOIN <tableref> 

ON <search_condition> \ (<joined_table>) 

<join-type> = ([INNER] | (LEFT | RIGHT | FULL } [OUTER]} JOIN 

<search_condition> = {<val> <operator> 

{<val> I {<select_one>)} 

I <val> [NOT] BETWEEN <val> AND <val> 

I <val> [NOT] LIKE <val> [ESCAPE <val>] 

I <val> [NOT] IN {<val> [, <val> ...] I <select_list>) 

I <val> IS [NOT] NULL 
I <val> {[NOT] {= I < I >} I >= I <=} 

{ALL I SOME I ANY} {<select_list>) 

I EXISTS (<select_expr>) 

I SINGULAR {<select_expr>) 

I <val> [NOT] CONTAINING <val> 

I <val> [NOT] STARTING [WITH] <val> 

I i<search_condition>) 

I NOT <search_condition> 

I <search_condition> OR <search_condition> 

I <search_condition> AND <search_condition>} 

<operator> = {= | < | > j <= | >= | !< | !> | <> | !=} 

<select_one> = SELECT on a single column that returns exactly one row. 

<select_list> = SELECT on a single column that returns zero or more 
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<select_expr> = SELECT on a list of values that returns zero or more 


<plan_expr> = 

[JOIN I [SORT] MERGE] (<plan_item> \ <plan_expr> 

[, <plan_item> \ <plan_expr> ...]) 

<plan_item> = {table \ alias) 

NATURAL I INDEX ( <index> [, <index> ...]) | ORDER <index> 

<order_list> = 

[col I int} [COLLATE collation] [ASC[ENDING] | DESC[ENDING]] 
[, <order_list>] 


Argument 

TRANSACTION 
transaction 
SELECT [DISTINCT 
I ALL] 

{* I <val> [, <val> ...] 

INTO :varl var...] 

FROM <tableref> 

[, <tableref>...] 

table 

view 

procedure 

alias 


<Joined_table> 

<Join_type> 

WHERE 

<search_condition> 
GROUP BY <col> 

[, <col >...] 
COLLATE collation 
HAVING 

<search_condition> 


Description 

Name of the transaction under control of which the statement is 
executed. SQL only. 

Specifies data to retrieve. DISTINCT prevents duplicate values 
from being returned. ALL, the default, retrieves every value. 

The asterisk (*) retrieves all columns for the specified tables. 
<val> [, <val> ...] retrieves a specific list of columns and values. 
Singleton select in embedded SQL only. Specifies a list of host- 
language variables into which to retrieve values. 

List of tables, views, and stored procedures from which to 
retrieve data. List can include joins and joins can be nested. 
Name of an existing table in a database. 

Name of an existing view in a database. 

Name of an existing stored procedure that functions like a 
SELECT statement. 

Brief, alternate name for a table, view, or column. After declara¬ 
tion in <tableref>, alias can stand in for subsequent references to 
a table or view. 

A table reference consisting of a JOIN. 

Type of join to perform. Default: INNER. 

Specifies a condition that limits rows retrieved to a subset of all 
available rows. 

Partitions the results of a query into groups containing all rows 
with identical values based on a column list. 

Specifies the collation order for the data retrieved by the query. 
Used with GROUP BY. Specifies a condition that limits grouped 
rows returned. 
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Argument 

Description 

UNION 

Combines two or more tables that are fully or partially identical in 
structure. 

PLAN <plan_expr> 

Specifies the access plan for the InterBase optimizer to use dur¬ 
ing retrieval. 

<plan_item> 

Specifies a table and index method for a plan. 

ORDER BY 
<order_list> 

Specifies the order in which rows are returned. 


Description SELECT retrieves data from tables, views, or stored procedures. Variations of the 
SELECT statement make it possible to: 

• Retrieve a single row, or part of a row, from a table. This operation is 
referred to as a singleton select. 

In embedded applications, all SELECT statements that occur outside the 
context of a cursor must be singleton selects. 

• Retrieve multiple rows, or parts of rows, from a table. 

In embedded applications, multiple row retrieval is accomplished by 
embedding a SELECT within a DECLARE CURSOR statement. 

In isql, SELECT can be used directly to retrieve multiple rows. 

• Retrieve related rows, or parts of rows, from a join of two or more tables. 

• Retrieve all rows, or parts of rows, from rmion of two or more tables. 

All SELECT statements consist of two required clauses (SELECT, EROM), and 
possibly others (INTO, WHERE, GROUP BY, HAVING, UNION, PLAN, ORDER 
BY). The following table explains the purpose of each clause, and when they are 
required: 


Table 2-11: SELECT Statement Clauses 


Clause Purpose 


Singleton Multi-row 
SELECT SELECT 


SELECT 

INTO 

FROM 

WHERE 


Lists columns to retrieve. Required 

Lists host variables for storing retrieved columns. Required 
Identifies the tables to search for values. Required 

Specifies the search conditions used to restrict Optional 


retrieved rows to a subset of all available rows. A 
WHERE clause may contain its own SELECT state¬ 
ment, referred to as a subquery. 


Required 
Not allowed 
Required 
Optional 
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Table 2-11: SELECT Statement Clauses (Continued) 


Clause 

Purpose 

Singleton 

SELECT 

Multi-row 

SELECT 

GROUP BY 

Groups related rows based on common column val¬ 
ues. Used In conjunction with HAVING. 

Optional 

Optional 

HAVING 

Restricts rows generated by GROUP BY to a subset 
of those rows. 

Optional 

Optional 

UNION 

Combines the results of two or more SELECT state¬ 
ments to produce a single, dynamic table without 
duplicate rows. 

Optional 

Optional 

ORDER BY 

Specifies the sort order of rows returned by a 
SELECT, either ascending (ASC), the default, or 
descending (DESC). 

Optional 

Optional 

PLAN 

Specifies the query plan that should be used by the 
query optimizer instead of one it would normally 
choose. 

Optional 

Optional 

FOR UPDATE 

Specifies columns listed after the SELECT clause of 
a DECLARE CURSOR statement that can be 
updated using a WHERE CURRENT OF clause. 


Optional 


Because SELECT is such a ubiquitous and complex statement, a meaningful dis¬ 
cussion lies outside the scope of this reference. To learn how to use SELECT in 
isql, see Getting Started. Eor a complete explanation of SELECT and its clauses, 
see the Programmer's Guide. 

Examples The following isql statement selects columns from a table: 

SELECT JOB_GRADE, JOB_CODE, JOB_COUNTRY, iyiAX_SALARY FROM PROJECT; 

The next isql statement uses the * wildcard to select all columns and rows from a 
table: 

SELECT * FROM COUNTRIES; 

The following embedded SQL statement uses an aggregate fimction to count all 
rows in a table that satisfy a search condition specified in the WHERE clause: 

EXEC SQL 

SELECT COUNT (*) INTO :cnt FROM COUNTRY 
WHERE POPULATION > 5000000; 

The next isql statement establishes a table alias in the SELECT clause and uses it 
to identify a column in the WHERE clause: 

SELECT C.CITY FROM CITIES C 

WHERE C.POPULATION < 1000000; 
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The following isql statement selects two columns and orders the rows retrieved 
by the second of those columns: 

SELECT CITY, STATE FROM CITIES 
ORDER BY STATE; 

The next isql statement performs a left join: 

SELECT CITY, STATE_NAME FROM CITIES C 

LEFT JOIN STATES S ON S.STATE = C.STATE 
WHERE C.CITY STARTING WITH "San"; 

The following isql statement specifies a query optimization plan for ordered 
retrieval, utilizing an index for ordering: 

SELECT * FROM CITIES 

PLAN (CITIES ORDER CITIES_1); 

ORDER BY CITY 

The next isql statement specifies a query optimization plan based on a three- 
way join with two indexed column equalities: 

SELECT * FROM CITIES C, STATES S, MAYORS M 

WHERE C.CITY = M.CITY AND C.STATE = M.STATE 
PLAN JOIN (STATE NATURAL, CITIES INDEX DUPE_CITY, 

MAYORS INDEX MAYORS_l) ; 

See Also DECLARE CURSOR, DELETE, INSERT, UPDATE 

Eor an introduction to using SELECT in isql, see Getting Started. 

Eor a full discussion of data retrieval in embedded programming using 
DECLARE CURSOR and SELECT, see the Programmer's Guide. 


SET DATABASE 

Declares a database handle for database access. Available in SQL. 

Syntax set {database I schema} dbhandle = 

[GLOBAL I STATIC I EXTERN] 

[COMPILETIME] [FILENAME] "<dbname>" 

[USER "<name>” PASSWORD "<string>”] 

[RUNTIME [FILENAME] {"<dbname>" \ :var} 

[USER {"<name>" \ : var} PASSWORD {"<string>" \ -.var}]]-, 
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Description 


Argument 

Description 

dbhandle 

An alias for a specified database. The alias must be unique 
within the program. It is used in subsequent SQL statements that 
support database handles. 

GLOBAL 

Default. Makes this database declaration available to all mod¬ 
ules. 

STATIC 

Limits scope of this database declaration to the current module. 

EXTERN 

References a database declaration in another module, rather 
than actually declaring a new handle. 

COMPILETIME 

Identifies the database used to look up column references during 
preprocessing. If only one database is specified in SET 
DATABASE, it is used both for run time and compile time. 

"<dbname>" 

Location and path name of the database associated with 
dbhandle. For specific platform file specifications, see that plat¬ 
form’s operating system manuals. 

RUNTIME 

Specifies a different database to use at run time than the one 
specified to use during preprocessing. 

:<var> 

Host-language variable containing a database specification, user 
name, or password. 

USER "<name>" 

Required for PC client attachments, optional for all others. A 
valid user name on the server where the database resides. Used 
with PASSWORD to gain database access on the server. 

PASSWORD 

"<string>" 

Required for PC client attachments, optional for all others. A 
valid password on the sen/er where the database resides. Used 
with USER to gain database access on the sen/er. 


SET DATABASE declares a database handle for a specified database and associ¬ 
ates the handle with that database. It enables optional specification of different 
compile-time and rim-time databases. Applications that access multiple data¬ 
bases simultaneously must use SET DATABASE statements to establish separate 
database handles for each database. 

dbhandle is an application-defined name for the database handle. Usually handle 
names are abbreviations of the actual database name. Once declared, database 
handles can be used in subsequent CONNECT, COMMIT, and ROLLBACK 
statements. They can also be used within transactions to differentiate table 
names when two or more attached databases contain tables with the same 
names. 
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''<dbname>'' is a platform-specific file specification for the database to associate 
with dbhandle. It should follow the file S5mtax conventions for the server where 
the database resides. 

GLOBAL, STATIC, and EXTERN are optional parameters that determine the 
scope of a database declaration. The default scope, GLOBAL, means that a data¬ 
base handle is available to all code modules in an application. STATIC limits 
database handle availability to the code module where the handle is declared. 
EXTERN references a global database handle in another module. 

The optional COMPILETIME and RUNTIME parameters enable a single data¬ 
base handle to refer to one database when an application is preprocessed, and to 
another database when an application is run by a user. If omitted, or if only a 
COMPILETIME database is specified, InterBase uses the same database during 
preprocessing and at run time. 

The USER and PASSWORD parameters are required for all PC client applica¬ 
tions, but are optional for all other remote attachments. The user name and pass¬ 
word are verified by the server in the security database before permitting remote 
attachments to succeed. 

Examples The following embedded SQL statement declares a handle for a database: 

EXEC SQL 

SET DATABASE DBl = "employee.gdb"; 

The next embedded SQL statement declares different databases at compile time 
and rim time. It uses a host-language variable to specify the run-time database. 

EXEC SQL 

SET DATABASE EMDBP = "employee.gdb" RUNTIME :db_name; 

See Also CQMMIT, CQNNECT, RQLLBACK, SELECT 

Eor more information on the security database, see the Windows Client User's 
Guide. 


SET GENERATOR 

Sets a new value for an existing generator. Available in SQL, DSQL, and isql. 

Syntax set generator name TO int; 
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Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument Description 

name Name of an existing generator. 

int Vaiue to which to set the generator, an integer from -2^"' to 2^C-| 


Description SET GENERATOR initializes a starting value for a newly created generator, or 
resets the value of an existing generator. A generator provides a imique, sequen¬ 
tial numeric value through the GEN_ID() fimction. If a newly created generator 
is not initialized with SET GENERATOR, its starting value defaults to zero. 

int is the new value for the generator. When the GEN_ID() fimction inserts or 
updates a value in a column, that value is int plus the increment specified in the 
GEN_ID() step parameter. 

Tip To force a generator's first insertion value to 1, use SET GENERATOR to 
specify a starting value of 0, and set the step value of the GEN_ID() func¬ 
tion to 1. 

Important When resetting a generator that supplies values to a column defined with 
PRIMARY KEY or UNIQUE integrity constraints, be careful that the new 
value does not enable duplication of existing column values, or all subse¬ 
quent insertions and updates will fail. 


Example The following isql statement sets a generator value to 1,000: 

SET GENERATOR CUST_NO_GEN TO 1000; 

If GEN_ID() now calls this generator with a step value of 1, the first number it 
returns is 1,001. 


See Also CREATE GENERATOR, CREATE PROCEDURE, CREATE TRIGGER, GEN_ID() 


SET NAMES 

Specifies an active character set to use for subsequent database attachments. 
Available in SQL, and isql. 

Syntax set names [charset I :var]; 
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SET NAMES 


Important 


Description 


Tip 


Important 


Exampie 


In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 


Argument 

Description 

charset 

Name of a character set that identifies the active character set for 
a given process. Default: NONE. 

war 

Host variable containing string identifying a known character set 
name. Must be declared as a character set name. SQL only. 


SET NAMES specifies the character set to use for subsequent database attach¬ 
ments in an application. It enables the server to translate between the default 
character set for a database on the server and the character set used by an appli¬ 
cation on the client. 

SET NAMES must appear before the SET DATABASE and CONNECT state¬ 
ments it is to affect. 

Use a host-language variable with SET NAMES in an embedded applica¬ 
tion to specify a character set interactively. 

Eor a complete list of character sets recognized by InterBase, see Appendix D: 
"Character Sets and Collation Orders." Choice of character sets limits possible 
collation orders to a subset of all available collation orders. Given a specific char¬ 
acter set, a specific collation order can be specified when data is selected, 
inserted, or updated in a column. 

If you do not specify a default character set, the character set defaults to 
NONE. Using character set NONE means that there is no character set 
assumption for columns; data is stored and retrieved just as you originally 
entered it. You can load any character set into a column defined with 
NONE, but you cannot load that same data into another column that has 
been defined with a different character set. No transliteration is performed 
between the source and destination character sets, so in most cases, errors 
occur during assignment. 

The following statements demonstrate the use of SET NAMES in an embedded 
SQL application: 

EXEC SQL 

SET NAMES IS08859_1; 

EXEC SQL 

SET DATABASE DBl = "employee.gdb"; 

EXEC SQL 

CONNECT; 
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SET STATISTICS 


See Also 

The next statements demonstrate the use of SET NAMES in isql: 

SET NAMES LATINl; 

CONNECT "employee.gdb"; 

CONNECT, SET DATABASE 

Eor more information about character sets and collation orders, see the Data Def¬ 
inition Guide. 


SET STATISTICS 



Recomputes the selectivity of a specified index. Available in SQL, DSQL, and 

isql. 

Syntax 

Important 

SET STATISTICS INDEX name; 

In SQL statements passed to DSQL, omit the terminating semicolon. In 
embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

Argument Description 

name Name of an existing Index for which to recompute selectivity. 

Description 

SET STATISTICS enables the selectivity of an index to be recomputed. Index 
selectivity is a calculation, based on the number of distinct rows in a table, that is 
made by the InterBase optimizer when a table is accessed. It is cached in mem¬ 
ory, where the optimizer can access it to calculate the optimal retrieval plan for a 
given query. Eor tables where the number of duplicate values in indexed col¬ 
umns radically increases or decreases, periodically recomputing index selectiv¬ 
ity can improve performance. 

Only the creator of an index can use SET STATISTICS. 

Note 

SET STATISTICS does not rebuild an index. To rebuild an index, use 

ALTER INDEX. 

Example 

The following embedded SQL statement recomputes the selectivity for an index: 

EXEC SQL 

SET STATISTICS INDEX MINSALX; 

See Also 

ALTER INDEX, CREATE INDEX, DRQP INDEX 
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SET TRANSACTION 


SET TRANSACTION 

Starts a transaction and optionally specifies its behavior. Available in SQL, 
DSQL, and isql. 

Syntax set transaction [name transaction] 

[READ WRITE | READ ONLY] 

[WAIT I NO WAIT] 

[[ISOLATION LEVEL] {SNAPSHOT [TABLE STABILITY] 

I READ COMMITTED [[NO] RECORD_VERSION]}] 

[RESERVING <reserving_clause> 

I USING dbhandle [, dbhandle ...]]; 

Important In SQL statements passed to DSQL, omit the terminating semicolon. In 

embedded applications written in C and C++, and in isql, the semicolon is 
a terminating symbol for the statement, so it must be included. 

<reserving_clause> = table [, table ...] 

[FOR [SHARED | PROTECTED] {READ | WRITE}] [, <reserving_clause>] 


Argument 

Description 

NAME transaction 

Specifies the name for this transaction, transaction is a previ¬ 
ously declared and initialized host-language variable. SQL only. 

READ WRITE 

Specifies that the transaction can read and write to tables 
(default). 

READ ONLY 

Specifies that the transaction can only read tables. 

WAIT 

Specifies that a transaction wait for access if it encounters a lock 
conflict with another transaction (default). 

NO WAIT 

Specifies that a transaction immediately return an error if it 
encounters a lock conflict. 

ISOLATION LEVEL 

Specifies the isolation level for this transaction when attempting 
to access the same tables as other simultaneous transactions. 
Default: SNAPSHOT. 

RESERVING 

<reserving_clause> 

Reserves lock for tables at transaction start. 

USING dbhandle 
[, dbhandle ...] 

Limits database access to a subset of available databases. SQL 
only. 


Description SET TRANSACTIQN starts a transaction, and optionally specifies its database 
access, lock conflict behavior, and level of interaction with other concurrent 
transactions accessing the same data. It can also reserve locks for tables. As an 
alternative to reserving tables, multiple database SQL applications can restrict a 
transaction's access to a subset of connected databases. 
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SET TRANSACTION 


Important Applications preprocessed with the gpre -manual switch must explicitly 
start each transaction with a SET TRANSACTION statement. 

SET TRANSACTION affects the default transaction rmless another transaction is 
specified in the optional NAME clause. Named transactions enable support for 
multiple, simultaneous transactions in a single application. All transaction 
names must be declared as host-language variables at compile time. In DSQL, 
this restriction prevents dynamic specification of transaction names. 

By default a transaction has READ WRITE access to a database. If a transaction 
only needs to read data, specify the READ ONLY parameter. 

When simultaneous transactions attempt to update the same data in tables, only 
the first update succeeds. No other transaction can update or delete that data 
until the controlling transaction is rolled back or committed. By default, transac¬ 
tions WAIT rmtil the controlling transaction ends, then attempt their own opera¬ 
tions. To force a transaction to return immediately and report a lock conflict 
error without waiting, specify the NO WAIT parameter. 

ISOLATION LEVEL determines how a transaction interacts with other simulta¬ 
neous transactions accessing the same tables. The default ISOLATION LEVEL is 
SNAPSHOT. It provides a repeatable-read view of the database at the moment 
the transaction starts. Changes made by other simultaneous transactions are not 
visible. 

SNAPSHOT TABLE STABILITY provides a repeatable read of the database by 
ensuring that transactions carmot write to tables, though they may still be able to 
read from them. 

READ COMMITTED enables a transaction to see the most recently committed 
changes made by other simultaneous transactions. It can also update rows as 
long as no update conflict occurs. Uncommitted changes made by other transac¬ 
tions remain invisible until committed. READ COMMITTED also provides two 
optional parameters: 

• NO REC0RD_VERS10N, the default, reads only the latest version of a 
row. If the WAIT lock resolution option is specified, then the transaction 
waits until the latest version of a row is committed or rolled back, and 
retries its read. 

• RECORD_VERSION reads the latest committed version of a row, even if 
more recent uncommitted version also resides on disk. 

The RESERVING clause enables a transaction to register its desired level of 
access for specified tables when the transaction starts instead of when the trans¬ 
action attempts its operations on that table. Reserving tables at transaction start 
can reduce the possibility of deadlocks. 
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Examples 


See Also 


SUMO 


Syntax 


Description 


The USING clause, available only in SQL, can be used to conserve system 
resources by limiting the number of databases a transaction can access. 

The following embedded SQL statement sets up the default transaction with an 
isolation level of READ CQMMITTED. If the transaction encounters an update 
conflict, it waits to get control until the first (locking) transaction is committed or 
rolled back. 

EXEC SQL 

SET TRANSACTION WAIT ISOLATION LEVEL READ COMMITTED; 

The next embedded SQL statement starts a named transaction: 

EXEC SQL 

SET TRANSACTION NAME T1 READ COMMITTED; 

The following embedded SQL statement reserves three tables: 

EXEC SQL 

SET TRANSACTION NAME TRl 
ISOLATION LEVEL READ COMMITTED 
NO RECORD_VERSION WAIT 

RESERVING TABLET, TABLE2 FOR SHARED WRITE, 

TABLES FOR PROTECTED WRITE; 

CQMMIT, RQLLBACK, SET NAMES 

For more information about transactions, see the Programmer's Guide. 


Totals the numeric values in a specified coluirm. Available in SQL, DSQL, and 


isql. 


SUM ([ALL] <val> 

1 DISTINCT <val>) 

Argument 

Description 

ALL 

DISTINCT 

<val> 

Totals all values in a column. 

Eliminates duplicate values before calculating the total. 

A column, constant, host-language variable, expression, non¬ 
aggregate function, or UDF that evaluates to a numeric data 
type. 


SUM() is an aggregate function that calculates the sum of numeric values for a 
column. If the number of qualifying rows is zero, SUM() returns a NULL value. 
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UPDATE 


Example 

See Also 

UPDATE 

Syntax 

Note 

Note 


The following embedded SQL statement demonstrates the use of SUM(), AVG(), 
M1N(), and MAX(): 

EXEC SQL 

SELECT SUM (BUDGET), AVG (BUDGET), MIN (BUDGET), MAX (BUDGET) 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :head_dept 

INTO :tot_budget, :avg_budget, :min_budget, :max_budget; 

AVG(), GOUNTO, MAX(), M1N() 


Ghanges the data in all or part of an existing row in a table, view, or active set of 
a cursor. Available in SQL, DSQL, and isql. 

SQL form: 

UPDATE [TRANSACTION transaction] {table \ view] 

SET col = <val> [, col = <val> ...] 

[WHERE <search_condition> \ WHERE CURRENT OF cursor ]; 

DSQL and isql form: 

UPDATE {table \ view] 

SET col = <val> [, col = <val> ...] 

[WHERE <search_condition> 

col l<array_dim>] | -.variable 
I <constant> \ <expr> \ <function> 

I udf ({<val> [, <val> ...]]) 

I NULL I USER I ?) 

[COLLATE collation] 

In SQL and isql, <val> cannot be a parameter placeholder (?). In DSQL and 
isql, <val> cannot be a variable. The GQLLATE clause cannot be used with 
BLQB values. 

<array_dim> = [x:y [, x:y ...]] 

Quteimost brackets, in bold, must be included when declaring arrays. 

<constant> = num \ "string" \ charsetname "string" 

<expr> = A valid SQL expression that results in a single value. 

<function> = ( 

CAST (<val> AS <datatype>) 

I UPPER (<val>) 
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UPDATE 


Description 

Caution 

Note 

Exampies 


See Aiso 


I GEN_ID {generator, <val>) 


<search_condition> = See CREATE TABLE for a full description. 


Argument 

Description 

TRANSACTION 

transaction 

Name of the transaction under controi of which the statement is 
executed. 

table 1 view 

Name of an existing tabie or view to update. 

SET col= <val> 

Specifies the columns to change and the values to assign to 
those columns. 

WHERE 

<search_condition> 

Searched update only. Specifies the conditions a row must meet 
to be modified. 

WHERE CURRENT 
OF cursor 

Positioned update only. Specifies that the current row of a cur¬ 
sor’s active set is to be modified. Not available in DSQL and isql. 


UPDATE modifies one or more existing rows in a table or view. UPDATE is one 
of the database privileges controlled by GRANT and REVOKE. 

Eor searched updates, the optional WHERE clause can be used to restrict 
updates to a subset of rows in the table. Searched updates cannot update array 
slices. 

Without a WHERE clause, a searched update modifies all rows in a table. 

When performing a positioned update with a cursor, the WHERE CURRENT OE 
clause must be specified to update one row at a time in the active set. 

When updating a BLOB column, UPDATE replaces the entire BLOB with a 
new value. 

The following isql statement modifies a column for all rows in a table: 

UPDATE CITIES 

SET POPULATION = POPULATION * 1.03; 

The next embedded SQL statement uses a WHERE clause to restrict column 
modification to a subset of rows: 

EXEC SQL 

UPDATE PROJECT 

SET PROJ_DESC = :blob_id 

WHERE PROJ_ID = :proj_id; 

DELETE, GRANT, INSERT, REVOKE, SELECT 
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UPPERC) 


UPPERO 

Converts a string to all uppercase. Available in SQL, DSQL, and isql. 

Syntax upper (<vai>) 


Argument 

Description 

<val> 

A column, constant, host-language variable, expression, func¬ 
tion, or UDF that evaluates to a character data type. 


Description UPPERQ converts a specified string to all uppercase characters. If applied to 
character sets that have no case differentiation, UPPER() has no effect. 


Exampies The following isql statement changes the name, BMatthews, to BMATTHEWS: 

UPDATE EMPLOYEE 

SET EMP_NAME = UPPER (BMatthews) 

WHERE EMP_NAME = "BMatthews"; 

The next isql statement creates a domain called PROJNO with a CHECK con¬ 
straint that requires the value of the coluirm to be all uppercase: 

CREATE DOMAIN PROJNO 
AS CHAR(5) 

CHECK (VALUE = UPPER (VALUE)); 


See Aiso CAST() 


WHENEVER 

Traps SQLCODE errors and warnings. Available in SQL. 

Syntax whenever {not found I SQLERROR | SQLWARNING} 

{GOTO label \ CONTINUE}; 


Argument 
NOT FOUND 

SOLERROR 

SOLWARNING 


Description 

Traps SOLCODE = 100, no qualifiying rows found for the exe¬ 
cuted statement. 

Traps SOLCODE < 0, failed statement. 

Traps SOLCODE > 0 AND < 100, system warning or informa¬ 
tional message. 
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WHENEVER 


Description 


Tip 

Exampie 

See Aiso 


Argument 

Description 

GOTO label 

Jumps to program location specified by label when a warning or 
error occurs. 

CONTINUE 

Ignores the warning or error and attempts to continue process¬ 
ing. 


WHENEVER traps for SQLCODE errors and warnings. Every executable SQL 
statement returns an SQLCODE value to indicate its success or failure. If 
SQLCODE is zero, statement execution is successful. A non-zero value indicates 
an error, warning, or not found condition. 

If the appropriate condition is trapped for, WHENEVER can: 

• Use GOTO label to jump to an error-handling routine in an application. 

• Use CONTINUE to ignore the condition. 

WHENEVER can help limit the size of an application, because the application 
can use a single suite of routines for handling all errors and warnings. 

WHENEVER statements should precede any SQL statement that can result in an 
error. Each condition to trap for requires a separate WHENEVER statement. If 
WHENEVER is omitted for a particular condition, it is not trapped. 

Precede error-handling routines with WHENEVER ... CONTINUE state¬ 
ments to prevent the possibility of infinite looping in the error-handling 
routines. 

In the following code from an embedded SQL application, three WHENEVER 
statements determine which label to branch to for error and warning handling: 

EXEC SQL 

WHENEVER SQLERROR GO TO Error; /* Trap all errors. */ 

EXEC SQL 

WHENEVER NOT FOUND GO TO AllDone; /* Trap SQLCODE = 100 */ 

EXEC SQL 

WHENEVER SQLWARNING CONTINUE; /* Ignore all warnings. */ 

Eor a complete discussion of error-handling methods and programming, see the 
Programmer's Guide. 
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CHAPTER 3 

Procedure and Trigger 
Language Reference 


InterBase procedure and trigger language is a complete programming language 
for writing stored procedures and triggers in isql and DSQL. It includes: 

• SQL data manipulation statements: INSERT, UPDATE, DELETE, and 
singleton SELECT. 

• Powerful extensions to SQL, including assignment statements, control- 
flow statements, context variables, event-posting, exceptions, and error 
handling. 

Although stored procedures and triggers are used in entirely different ways and 
for different purposes, they both use procedure and trigger language. Both trig¬ 
gers and stored procedures can use any statements in procedure and trigger lan¬ 
guage, with some exceptions: 

• QLD and NEW context variables are unique to triggers. 

• Input and output parameters, and the SUSPEND and EXIT statements 
are unique to stored procedures. 

The Data Definition Guide explains how to create and use stored procedures and 
triggers. This chapter is a reference for the statements that are unique to trigger 
and procedure language or that have special S5mtax when used in triggers and 
procedures. 


Creating Triggers and Stored Procedures 

Stored procedures and triggers are defined with the CREATE PRQCEDURE and 
CREATE TRIGGER statements, respectively. Each of these statements is com¬ 
posed of a header and a body. 

The header contains: 

• The name of the procedure or trigger, unique within the database. 
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For a trigger: 


• A table name, identifying the table that causes the trigger to fire. 

• Statements that determine when the trigger fires. 

• For a stored procedure: 

• An optional list of input parameters and their data types. 

• If the procedure returns values to the calling program, RETURNS fol¬ 
lowed by a list of output parameters and their data t5^es. 

The body contains: 

• An optional list of local variables and their data t5^es. 

• A block of statements in InterBase procedure and trigger language, brack¬ 
eted by BEGIN and END. A block can itself include other blocks, so that 
there may be many levels of nesting. 

Important Because each statement in a stored procedure body must be terminated by 
a semicolon, you must define a different symbol to terminate the CREATE 
PROCEDURE statement in isql. Use SET TERM before CREATE 
PROCEDURE to specify a terminator other than a semicolon. After the 
CREATE PROCEDURE statement, include another SET TERM to change 
the terminator back to a semicolon. 


Nomenclature Conventions 

This chapter uses the following nomenclature: 

• A block is one or more compound statements enclosed by BEGIN and 
END. 

• A compound statement is either a block or a statement. 

• A statement is a single statement in procedure and trigger language. 
To illustrate in a S5mtax diagram: 

<block> = 

BEGIN 

<compound_statement> 

[<compound_statement> ...] 

END 

<compound_statement> = 

{<block> I statement;] 
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Assignment Statement 


Assignment Statement 

Assigns a value to an input or output parameter or local variable. Available in 
triggers and stored procedures. 

Syntax variable = <expression>} 


Argument 

Description 

variable 

<expression> 

A local variable, input parameter, or output parameter. 

Any valid combination of variables, SQL operators, and expres¬ 
sions, including user-defined functions (UDFs) and generators. 


Description An assignment statement sets the value of a local variable, input parameter, or 
output parameter. Variables must be declared before they can be used in assign¬ 
ment statements. 


Example 


The first assignment statement below sets the value of x to 9. The second state¬ 
ment sets the value of y at twice the value of x. The third statement uses an arith¬ 
metic expression to assign z a value of 3. 


DECLARE VARIABLE x 
DECLARE VARIABLE y 
DECLARE VARIABLE z 


INTEGER; 

INTEGER; 

INTEGER; 


X = 9; 
y = 2 * x; 


(y - 6); 


See Also DECLARE VARIABLE, Input Parameters, Output Parameters 


BEGIN... END 

Defines a block of statements executed as one. Available in triggers and stored 
procedures. 

Syntax <block> = 

BEGIN 

<compound_statement> 
l<compound_statement> ...] 

END 

<compound_statement> = 

{<block> I statement;} 
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Comment 


Description Each block of statements in the procedure body starts with a BEGIN statement 
and ends with an END statement. As shown in the above syntax diagram, a 
block can itself contain other blocks, so there may be many levels of nesting. 

BEGIN and END are not followed by a semicolon. In isql, the final END in the 
procedure body is followed by the terminator specified by SET TERM. 

The final END statement in a trigger terminates the trigger. The final END state¬ 
ment in a stored procedure operates differently, depending on the t 5 q)e of 
procedure: 

• In a select procedure, the final END statement returns control to the 
application and sets SQLGODE to 100, which indicates there are no more 
rows to retrieve. 

• In an executable procedure, the final END statement returns control and 
current values of output parameters, if any, to the calling application. 

Example The following isql fragment of the DELETE_EMPLOYEE procedure shows two 
examples of BEGIN ... END blocks. 

SET TERM ! ! ; 

CREATE PROCEDURE DELETE_EMPLOYEE (EMP_NUM INTEGER) 

AS 

DECLARE VARIABLE ANY_SALES INTEGER; 

BEGIN 

ANY_SALES = 0; 

IF (ANY_SALES > 0) THEN 
BEGIN 

EXCEPTION REASSIGN_SALES; 

EXIT; 

END 

END ! ! 

See Also EXIT, SUSPEND 


Comment 


Allows programmers to add comments to procedure and trigger code. Available 
in triggers and stored procedures. 

Syntax /* comment_text */ 
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DECLARE VARIABLE 


Argument 

Description 

commentjext 

Any number of lines of comment text. 


Description Comments can be placed on the same line as code, or on separate lines. 

It is good programming practice to state the input and output parameters of a 
procedure in a comment preceding the procedure. It is also often useful to com¬ 
ment local variable declarations to indicate what each variable is used for. 


Exampie The following isql procedure fragment illustrates some ways to use comments: 

/* 

* Procedure DELETE_EMPLOYEE : Delete an employee. 

* Parameters: 

* employee number 

* Returns: 


CREATE PROCEDURE DELETE_EMPLOYEE (EMP_NUM INTEGER) 

AS 

DECLARE VARIABLE ANY_SALES INTEGER; /* Number of sales for emp. /* 
BEGIN 


DECLARE VARIABLE 

Declares a local variable. Available in triggers and stored procedures. 

Syntax declare variable var datatype; 


Argument 

Description 

var 

datatype 

Name of the local variable, unique within the trigger or procedure. 
Data type of the iocai variabie. Can be any InterBase data type 
except BLOB and arrays. 


Description Local variables are declared and used within a stored procedure. They have no 
effect outside the procedure. 

Local variables must be declared at the beginning of a procedure body before 
they can be used. Each local variable requires a separate DECLARE VARIABLE 
statement, followed by a semicolon (;). 
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EXCEPTION 


Example 

The following header declares the local variable, ANY_SALES: 

CREATE PROCEDURE DELETE_EMPLOYEE (EMP_NUM INTEGER) 

AS 

DECLARE VARIABLE ANY_SALES INTEGER; 

BEGIN 

See Also 

Input parameters. Output parameters 


EXCEPnON 



Raises the specified exception. Available in triggers and stored procedures. 

Syntax 

EXCEPTION name; 

Argument Description 

name Name of the exception being raised. 

Description 

An exception is a user-defined error that has a name and an associated text mes¬ 
sage. When raised, an exception: 

• Terminates the procedure or trigger in which it was raised and undoes 
any actions performed (directly or indirectly) by the procedure or trigger. 

• Returns an error message to the calling application. In isql, the error 
message is displayed to the screen. 

Exceptions can be handled with the WHEN statement. If an exception is han¬ 
dled, it will behave differently. 

Example 

The following isql statement defines an exception named REASSIGN_SALES: 

CREATE EXCEPTION REASSIGN_SALES 

"Reassign the sales records before deleting this employee." !! 

Then these statements from a procedure body raise the exception: 

IF (ANY_SALES > 0) THEN 

EXCEPTION REASSIGN_SALES; 

See Also 

WHEN... DO 

Eor more information on creating exceptions, see "CREATE EXCEPTION" in 
Chapter 2: "SQL Statement and Eunction Reference." 
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EXECUTE PROCEDURE 


EXECUTE PROCEDURE 


Executes a stored procedure. Available in triggers and stored procedures. 


Syntax execute procedure name [iparam [, iparam ...]] 

[RETURNING_VALUES iparam [, iparam ...]]; 


Argument 

Description 

name 

Name of the procedure being executed. Must have been previously 
defined to the database with CREATE PROCEDURE. 

[param 
[, param ...]] 

List of input parameters, if the procedure requires them. Can be 
constants or variables. Precede variables with a colon, except NEW 
and OLD context variables. 

[RETURNING_ 
VALUES param 
[, param ...]] 

List of output parameters, if the procedure returns values. Precede 
each with a colon, except NEW and OLD context variables. 


Description A stored procedure can itself execute a stored procedure. Each time a stored pro¬ 
cedure calls another procedure, the call is said to be nested because it occurs in 
the context of a previous and still active call to the first procedure. A stored pro¬ 
cedure called by another stored procedure is known as a nested procedure. 

If a procedure calls itself, it is recursive. Recursive procedures are useful for tasks 
that involve repetitive steps. Each invocation of a procedure is referred to as an 
instance, since each procedure call is a separate entity that performs as if called 
from an application, reserving memory and stack space as required to perform 
its tasks. 

Note Stored procedures can be nested up to 1,000 levels deep. This limitation 
helps to prevent infinite loops that can occur when a recursive procedure 
provides no absolute terminating condition. Nested procedure calls may 
be restricted to fewer than 1,000 levels by memory and stack limitations of 
the server. 


Example The following isql example illustrates a recursive procedure, EACTORIAL, 

which calculates factorials. The procedure calls itself recursively to calculate the 
factorial of NUM, the input parameter. 

SET TERM ! ! ; 

CREATE PROCEDURE FACTORIAL (NUM INT) 

RETURNS (N_FACTORIAL DOUBLE PRECISION) 

AS 

DECLARE VARIABLE NUM_LESS_ONE INT; 

BEGIN 

IF (NUM = 1) THEN 
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EXIT 


BEGIN /**** Base case: 1 factorial is 1 ****/ 

N_FACTORIAL = 1; 

EXIT; 

END 

ELSE 

BEGIN /**** Recursion: num factorial = num * (num-1) factorial ****/ 
NUM_LESS_ONE = NUM - 1; 

EXECUTE PROCEDURE FACTORIAL NUM_LESS_ONE 
RETURNING_VALUES N_FACTORIAL; 

N_FACTORIAL = N_FACTORIAL * NUM; 

EXIT; 

END 
END! I 

SET TERM ; ! ! 

See Also CREATE PROCEDURE, Input Parameters, Output Parameters 

Por more information on executing procedures, see "EXECUTE PROCEDURE" 
in Chapter 2: "SQL Statement and Punction Reference." 


EXIT 

Jumps to the final END statement in the procedure. Available in stored proce¬ 
dures only. 

Syntax exit; 

Description In both select and executable procedures, EXIT jumps program control to the 
final END statement in the procedure. 

What happens when a procedure reaches the final END statement depends on 
the type of procedure: 

• In a select procedure, the final END statement returns control to the 
application and sets SQLCODE to 100, which indicates there are no more 
rows to retrieve. 

• In an executable procedure, the final END statement returns control and 
values of output parameters, if any, to the calling application. 

SUSPEND also returns values to the calling program. Each of these statements 
has specific behavior for executable and select procedures, as shown in the fol¬ 
lowing table. 
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Table 3-1: SUSPEND, EXIT, and END 


Procedure Type 

SUSPEND 

EXIT 

END 

Select 

procedure 

Suspends execution 
of procedure until next 
FETCH is issued. 
Returns output values. 

Jumps to final END. 

Returns control to 
application. 

Sets SQLCODE to 

100 (end of record 
stream). 

Executable 

procedure 

Jumps to final END. 
Not Recommended. 

Jumps to final END. 

Returns values. 

Returns control to 
application. 


Example Consider the following procedure from an isql script: 

SET TERM ! ! ; 

CREATE PROCEDURE P RETURNS (r INTEGER) 

AS 

BEGIN 

r = 0; 

WHILE (r < 5) DO 
BEGIN 

r = r + 1; 

SUSPEND; 

IF (r = 3) THEN 
EXIT; 

END 
END! ! 

SET TERM ; I I 

If this procedure is used as a select procedure in isql, for example, 

SELECT * FROM P; 

then it will return values 1,2, and 3 to the calling application, since the 
SUSPEND statement returns the current value of r to the calling application. The 
procedure terminates when it encoimters EXIT. 

If the procedure is used as an executable procedure in isql, for example, 

EXECUTE PROCEDURE P; 

then it will return 1, since the SUSPEND statement will terminate the procedure 
and return the current value of r to the calling application. SUSPEND should not 
be used in an executable procedure, so EXIT would be used instead. 

See Also BEGIN ... END, SUSPEND 
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FOR SELECT ... DO 


FOR SELECT... DO 

Repeats a block or statement for each row retrieved by the SELECT statement. 
Available in triggers and stored procedures. 

Syntax for 

<select_expr> 

<compound_statement> 


Argument Description 

<select_expr> SELECT statement that retrieves rows from the database. The 

INTO clause is required and must come last. 
<compound_statement> Statement or block executed once for each row retrieved by 
the SELECT statement. 


Description EOR SELECT is a loop statement that retrieves the row specified in the 

<select_expr> and performs the statement or block following DO for each row 
retrieved. 

The <select_expr> is a normal SELECT, except the INTO clause is required and 
must be the last clause. 

Example The following isql statement selects department numbers into the local variable, 
RDNO, which is then used as an input parameter to the DEPT_BUDGET 
procedure: 

FOR SELECT DEPT_NO 
FROM DEPARTMENT 
WHERE HEAD_DEPT = :DNO 
INTO :RDNO 
DO 

BEGIN 

EXECUTE PROCEDURE DEPT_BUDGET :RDNO RETURNING_VALUES :SUMB; 

TOT = TOT + SUMB; 

END 

See Also SELECT 


138 


Language Reference 






IF . . . THEN . . . ELSE 


IF...THEN...ELSE 


Conditional statement that performs a block or statement in the IF clause if the 
specified condition is TRUE, otherwise performs the block or statement in the 
optional ELSE clause. Available in triggers and stored procedures. 

Syntax if (<condition>) THEN 

<compound_statement> 

[ELSE 

<compound_statement>] 


Argument 

<condition> 

THEN 

<compound_statement> 

[ELSE 

<compound_statement>] 


Description 

Boolean expression that evaluates to TRUE, FALSE, or 
UNKNOWN. Must be enclosed in parentheses. 

Statement or block executed If <condition> is TRUE. 

Optional statement or block executed if <condition> is not 
TRUE. 


Description The IE ... THEN ... ELSE statement selects alternative courses of action by test¬ 
ing a specified condition. <condition> is an expression that must evaluate to 
TRUE to execute the statement or block following THEN. The optional ELSE 
clause specifies an alternative statement or block executed if <condition> is not 
TRUE. 

Example The following lines of code illustrate the use of IE... THEN, assuming the vari¬ 
ables LINE2, EIRST, and LAST have been previously declared: 


IF (FIRST IS NOT NULL) THEN 

LINE2 = FIRST || " " || LAST; 

ELSE 

LINE2 = LAST; 


See Also WHILE ... DO 


Input Parameters 

Used to pass values from an application to a stored procedure. Available in 
stored procedures only. 
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NEW Context Variables 


Syntax 

CREATE PROCEDURE name 

1iparam datatype [, param datatype ...])] 

Description 

Input parameters are used to pass values from an application to a stored proce¬ 
dure. They are declared in a comma-delimited list in parentheses following the 
procedure name in the header of CREATE PROCEDURE. Once declared, they 
can be used in the procedure body an 5 rwhere a variable can appear. 

Input parameters are passed by value from the calling program to a stored proce¬ 
dure. This means that if the procedure changes the value of an input variable, 
the change has effect only within the procedure. When control returns to the 
calling program, the input variable will still have its original value. 

Input parameters can be of any InterBase data t}^e except BLOB. Arrays of data 
t 5 ^es are also unsupported. 

Exampie 

The following procedure header, from an isql script, declares two input parame¬ 
ters, EMP_NO and PROJJD: 

CREATE PROCEDURE ADD_EMP_PROJ (EMP_NO SMALLINT, PROJ_ID CHAR(5)) 

AS 

See Aiso 

DECLARE VARIABLE 

Eor more information on declaring input parameters in a procedure header, see 
"CREATE PROCEDURE" in Chapter 2: "SQL Statement and Ermction Refer¬ 
ence." 


NEW Context Variables 



Indicates a new column value in an INSERT or UPDATE operation. Available in 
triggers only. 

Syntax 

NEW.column 

Argument Description 

column Name of a column in the affected row. 

Description 

Triggers support two context variables: OLD and NEW. A NEW context variable 
refers to the new value of a column in an INSERT or UPDATE operation. 
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OLD Context Variables 


Context variables are often used to compare the values of a column before and 
after it is modified. Context variables can be used anywhere a regular variable 
can be used. 

New values for a row can only be altered before actions. A trigger that fires after 
INSERT and tries to assign a value to NEW.column will have no effect. However, 
the actual column values are not altered until after the action, so triggers that ref¬ 
erence values from their target tables will not see a newly inserted or updated 
value unless they fire after UPDATE or INSERT. 

Example The following isql script is a trigger that fires after the EMPLOYEE table is 

updated, and compares an employee's old and new salary. If there is a change in 
salary, the trigger inserts an entry in the SALARY_HlSTORY table. 

SET TERM !! ; 

CREATE TRIGGER SAVE_SALARY_CHANGE FOR EMPLOYEE 

AFTER UPDATE AS 

BEGIN 

IF (OLD.SALARY <> NEW.SALARY) THEN 
INSERT INTO SALARY_HISTORY 

(EMP_NO, CHANGE_DATE, UPDATER_ID, OLD_SALARY, PERCENT_CHANGE) 
VALUES (OLD.EMP_NO, "NOW", USER, OLD.SALARY, 

(NEW.SALARY - OLD.SALARY) * 100 / OLD.SALARY); 

END ! ! 

SET TERM ; !! 

See Also OLD Context Variables 

For more information on creating triggers, see "CREATE TRIGGER" in Chapter 
2: "SQL Statement and Function Reference." 


OLD Context Variables 

Indicates a current column value in an UPDATE or DELETE operation. Avail¬ 
able in triggers only. 

Syntax O-LD. column 


Argument 

Description 

column 

Name of a column in the affected row. 


Description Triggers support two context variables: OLD and NEW. An OLD context vari¬ 
able refers to the current or previous value of a column in an INSERT or 
UPDATE operation. 
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Output Parameters 



Context variables are often used to compare the values of a column before and 
after it is modified. Context variables can be used anywhere a regular variable 
can be used. 

Example 

The following isql script is a trigger that fires after the EMPLOYEE table is 
updated, and compares an employee's old and new salary. If there is a change in 
salary, the trigger inserts an entry in the SALARY_HISTORY table. 

SET TERM !! ; 

CREATE TRIGGER SAVE_SALARY_CHANGE FOR EMPLOYEE 

AFTER UPDATE AS 

BEGIN 

IF {OLD.SALARY <> NEW.SALARY) THEN 

INSERT INTO SALARY_HISTORY 

(EMP_NO, CHANGE_DATE, UPDATER_ID, OLD_SALARY, PERCENT_CHANGE) 
VALUES (OLD.EMP_NO, 'NOW', USER, OLD.SALARY, 

(NEW.SALARY - OLD.SALARY) * 100 / OLD.SALARY); 

END ! ! 

SET TERM ; !! 

See Also 

NEW Context Variables 

For more information about creating triggers, see "CREATE TRIGGER" in 
Chapter 2: "SQL Statement and Function Reference." 


Output Parameters 



Used to return values from a stored procedure to the calling application. Avail¬ 
able in stored procedures only. 

Syntax 

CREATE PROCEDURE name 

[iparam datatype [, param datatype ...])] 

[RETURNS {param datatype [, param datatype ...])] 

Description 

Output parameters are used to return values from a procedure to the calling 
application. They are declared in a comma-delimited list in parentheses follow¬ 
ing the RETURNS ke 5 rword in the header of CREATE PROCEDURE. Once 
declared, they can be used in the procedure body anywhere a variable can 
appear. They can be of any InterBase data t 5 ^e except BLOB. Arrays of data 
t 5 ^es are also unsupported. 

If output parameters are declared in a procedure's header, the procedure must 
assign them values to return to the calling application. Values can be derived 
from any valid expression in the procedure. 
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A procedure returns output parameter values to the calling application with a 
SUSPEND statement. An application receives values of output parameters from 
a select procedure by using the INTO clause of the SELECT statement. An appli¬ 
cation receives values of output parameters from an executable procedure by 
using the RETURNING_VALUES clause. 

In a SELECT statement that retrieves values from a procedure, the column 
names must match the names and data types of the procedure's output parame¬ 
ters. In an EXECUTE PROCEDURE statement, the output parameters need not 
match the names of the procedure's output parameters, but the data types must 
match. 

Example 

The following isql script is a procedure header declares five output parameters, 
HEAD_DEPT, DEPARTMENT, MNGR_NAME, TITLE, and EMP_CNT. 

CREATE PROCEDURE ORG_CHART RETURNS (HEAD_DEPT CHAR(25), DEPARTMENT 
CHAR(25), MNGR_NAME CHAR(20), TITLE CHAR(5), EMP_CNT INTEGER) 

See Also 

Eor more information on declaring output parameters in a procedure, see "CRE¬ 
ATE PROCEDURE" in Chapter 2: "SQL Statement and Eunction Reference." 


POST.EVENT 



Posts an event. Available in triggers and stored procedures. 

Syntax 

POST_EVENT "event_name" \ col; 

Argument Description 

”event_name" Name of the event being posted. Must be enclosed in quotes. 

Description 

POST_EVENT posts an event to the event manager. When an event occurs, this 
statement will notify the event manager, which alerts applications waiting for 
the named event. 

Example 

The following statement posts an event named "new_order": 

P0ST_EVENT "new_order"; 

The next statement posts an event based on the current value of a column: 

P0ST_EVENT NEW.COMPANY; 

See Also 

EVENT INIT, EVENT WAIT 

Eor more information on events, see the Programmer's Guide. 
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SELECT 


SELEa 


Retrieves a single row that satisfies the requirements of the search condition. The 
same as standard singleton SELECT, with some differences in S 5 mtax. Available 
in triggers and stored procedures. 

Syntax <select_expr> = <select_clause> <from_clause> 

[<where_clause>] [<group_by_clause>] 

[<having_clause>] 

[<union_expression>] [<plan_clause>] 

[<ordering_clause>] 


Description In a stored procedure, use the SELECT statement with an INTO clause to 

retrieve a single row value from the database and assign it to a host variable. The 
SELECT statement must return at most one row from the database, like a stan¬ 
dard singleton SELECT. The INTO clause is required and must be the last clause 
in the statement. 

The INTO clause comes at the end of the SELECT statement to allow the use of 
UNION operators. UNION is not allowed in singleton SELECT statements in 
embedded SQL. 

Exampie The following statement is a standard singleton SELECT statement in an embed¬ 
ded application: 

EXEC SQL 

SELECT SUM(BUDGET), AVG(BUDGET) 

INTO :TOT_BUDGET, :AVG_BUDGET 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :HEAD_DEPT 

To use the above SELECT statement in a procedure, move the INTO clause to the 
end as follows: 

SELECT SUM(BUDGET), AVG(BUDGET) 

FROM DEPARTMENT 

WHERE HEAD_DEPT = :HEAD_DEPT 

INTO :TOT_BUDGET, :AVG_BUDGET; 

See Aiso EOR SELECT ... DO 

Eor a complete explanation of the standard SELECT S 5 mtax, see "SELECT" in 
Chapter 2: "SQL Statement and Eunction Reference." 
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SUSPEND 


SUSPEND 

Suspends execution of a select procedure until the next FETCH is issued and 
returns values to the calling application. Available in stored procedures only. 

Syntax suspend; 

Description The SUSPEND statement: 

• Suspends execution of a stored procedure until the application issues the 
next EETCH. 

• Returns values of output parameters, if any. 

A procedure should ensure that all output parameters are assigned values 
before a SUSPEND. 

SUSPEND should not be used in an executable procedure. Use EXIT instead to 
indicate to the reader explicitly that the statement terminates the procedure. 

The following table summarizes the behavior of SUSPEND, EXIT, and END. 


Table 3-2: SUSPEND, EXIT, and END 


Procedure Type 

SUSPEND 

EXIT 

END 

Select 

procedure 

Suspends execution 
of procedure until next 
FETCH is issued. 
Returns output values. 

Jumps to final END. 

Returns control to 
application. 

Sets SQLCODE to 

100 (end of record 
stream). 

Executable 

procedure 

Jumps to final END. 
Not Recommended. 

Jumps to final END. 

Returns values. 

Returns control to 
application. 


Note If a SELECT procedure has executable statements following the last 

SUSPEND in the procedure, all of those statements are executed, even 
though no more rows are returned to the calling program. The procedure 
terminates with the final END statement, which sets SQLCODE to 100. 

The SUSPEND statement also delimits atomic statement blocks in select proce¬ 
dures. If an error occurs in a select procedure—either an SQLCODE error, 
GDSCODE error, or exception—the statements executed since the last 
SUSPEND and undone. Statements before the last SUSPEND are never imdone, 
unless the transaction comprising the procedure is rolled back. 
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WHEN ... DO 


Example 


See Also 

WHEN. 

Syntax 


The following procedure, from an isql script, illustrates the use of SUSPEND 
and EXIT: 

SET TERM ! ! ; 

CREATE PROCEDURE P RETURNS (R INTEGER) 

AS 

BEGIN 

R = 0; 

WHILE (R < 5) DO 
BEGIN 

R = R + 1; 

SUSPEND; 

IF (R = 3) THEN 
EXIT; 

END 

END; 

SET TERM ;!! 

If this procedure is used as a select procedure in isql, for example, 

SELECT * FROM P; 

then it will return values 1,2, and 3 to the calling application, since the 
SUSPEND statement returns the current value of r to the calling application 
until r = 3, when the procedure performs an EXIT and terminates. 

If the procedure is used as an executable procedure in isql, for example, 

EXECUTE PROCEDURE P; 

then it will return 1, since the SUSPEND statement will terminate the procedure 
and return the current value of r to the calling application. Since SUSPEND 
should not be used in executable procedures, EXIT would be used instead, indi¬ 
cating that when the statement is encoxmtered, the procedure is exited. 

EXIT, BEGIN ... END 


.DO 

Error-handling statement that performs the statements following DO when the 
specified error occurs. Available in triggers and stored procedures. 

WHEN {<error> [, <error> ...] | ANY} 

DO <compound_statement> 
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WHEN ... DO 


<error>= 

{EXCEPTION exception_name \ SQLCODE number | GDSCODE errcode] 


Argument 


Description 


EXCEPTION The name of an exception already in the database. 

exception name 

SQLCODE number An SQLCODE error code number. 

GDSCODE errcode An InterBase error code number. 

ANY Keyword that handles any of the above types of errors. 

<compound_statement> Statement or block executed when any of the specified errors 


Description Procedures can handle three kinds of errors with a WHEN statement: 

• Exceptions raised by EXCEPTION statements in the current procedure, 
in a nested procedure, or in a trigger fired as a result of actions by such a 
procedure. 

• SQL errors reported in SQLCODE. 

• InterBase error codes. 

The WHEN ANY statement handles any of the three t 5 ^es. 

Handiing Exceptions 

Instead of terminating when an exception occurs, a procedure can respond to 

and perhaps correct the error condition by handling the exception. When an 

exception is raised, it: 

• Terminates execution of the BEGIN ... END block containing the excep¬ 
tion and undoes any actions performed in the block. 

• Backs out one level to the next BEGIN ... END block and seeks an excep¬ 
tion-handling (WHEN) statement, and continues backing out levels until 
one is found. If no WHEN statement is found, the procedure is termi¬ 
nated and all its actions are undone. 

• Performs the ensuing statement or block of statements specified after 
WHEN, if found. 

• Returns program control to the block or statement in the procedure fol¬ 
lowing the WHEN statement. 

Note An exception that is handled with WHEN does not return an error 

message. 
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WHEN ... DO 


Handling SQL Errors 

Procedures can also handle error numbers returned in SQLCODE. After each 
SQL statement executes, SQLCODE contains a status code indicating the success 
or failure of the statement. It can also contain a warning status, such as when 
there are no more rows to retrieve in a LOR SELECT loop. 

Handling InterBase Error Codes 

Procedures can also handle InterBase error codes. Lor example, suppose a state¬ 
ment in a procedure attempts to update a row already updated by another trans¬ 
action, but not yet committed. In this case, the procedure might receive an 
InterBase error code, isc_lock_conflict. Perhaps if the procedure retries its 
update, the other transaction may have rolled back its changes and released its 
locks. By using a WHEN GDSCODE statement, the procedure can handle lock 
conflict errors and retry its operation. 

Example Lor example, if a procedure attempts to insert a duplicate value into a column 
defined as a PRIMARY KEY, InterBase will return SQLCQDE -803. This error can 
be handled in a procedure with the following statement: 

WHEN SQLCODE -803 
DO 

BEGIN 

Eor example, the following procedure, from an isql script, includes a WHEN 
statement to handle errors that may occur as the procedure nms. If an error 
occurs and SQLCQDE is as expected, the procedure continues with the new 
value of B. If not, the procedure carmot handle the error, and rolls back all 
actions of the procedure, returning the active SQLCQDE. 

SET TERM !!; 

CREATE PROCEDURE NUMBERPROC (A INTEGER) RETURNS (B INTEGER) AS 
BEGIN 

B = 0; 

BEGIN 

UPDATE R SET FI = FI + :A; 

UPDATE R SET F2 = F2 * F2; 

UPDATE R SET FI = FI + :A; 

WHEN SQLCODE -803 DO 

B = I; 

END 

EXIT; 

END! ! 

SET TERM; !! 
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WHILE ... DO 


See Also EXCEPTION 

Eor more information about InterBase error codes and SQLCODE values, see 
Appendix B: "Error Codes and Messages." 


WHILE... DO 

Performs the statement or block following DO as long as the specified condition 
is TRUE. Available in triggers and stored procedures. 

Syntax while (<condition>) DO 

<compound_statement> 


Argument Description 

<condition> Boolean expression tested before each execution of the state¬ 

ment or block following DO. 

<compound_statement> Statement or block executed as long as <condition> is TRUE. 

Description WHILE ... DO is a looping statement that repeats a statement or block of state¬ 
ments as long as a condition is true. The condition is tested at the start of each 
loop. 

Example The following procedure, from an isql script, uses a WHILE ... DO loop to com¬ 
pute the sum of all integers from one up to the input parameter: 

SET TERM ! ! ; 

CREATE PROCEDURE SUM_INT (I INTEGER) RETURNS (S INTEGER) 

AS 

BEGIN 

S = 0; 

WHILE (I > 0) DO 
BEGIN 

S = S + I; 

I = I - I; 

END 
END! ! 

SET TERM ; !! 

If this procedure is called from isql with the command: 

EXECUTE PROCEDURE SUM_INT 4; 


Procedure and Trigger Language Reference 


149 






WHILE ... DO 


See Also 


then the results will be: 


IF ... THEN, FOR SELECT ... DO 
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Appendix A 

Keywords 


The table in this appendix lists keywords, words reserved from use in SQL pro¬ 
grams and isql (Interactive SQL). The list includes SQL, DSQL, isql, and gpre 
ke5nvords. 

Ke5nvords are defined for special purposes, and are sometimes called reserved 
words. A ke5rword cannot occur in a user-declared identifier or as the name of a 
table, column, index, trigger, or constraint. Ke5rwords are: 

• Part of statements 

• Used as statements 

• Names of standard data structures or data t5^es 
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InterBase Keywords 


ACTIVE 

ADD 

AFTER 

ALL 

ALTER 

AND 

ANY 

AS 

ASC 

ASCENDING 

AT 

AUTO 

AUTODDL 

AVG 

BASED 

BASENAME 

BASE_NAME 

BEFORE 

BEGIN 

BETWEEN 

BLOB 

BLOBEDIT 

BUFFER 

BY 

CACHE 

CAST 

CHAR 

CHARACTER 

CHARACTER_LENGTH 

CHAR_LENGTH 

CHECK 


COLLATE 

COLLATION 

COLUMN 

COMMIT 

COMMITTED 

COMPILETIME 

COMPUTED 

CLOSE 

CONDITIONAL 

CONNECT 

CONSTRAINT 

CONTAINING 

CONTINUE 

COUNT 

CREATE 

CSTRING 

CURRENT 

CURSOR 

DATABASE 

DATE 

DB_KEY 

DEBUG 

DEC 

DECIMAL 

DECLARE 

DEFAULT 

DELETE 

DESC 

DESCENDING 

DESCRIBE 

DESCRIPTOR 


CHECK_POINT_LEN DISCONNECT 

CHECK_POINT_LENGTH DISTINCT 


DO 

DOMAIN 

DOUBLE 

DROP 

ECHO 

EDIT 

ELSE 

END 

ENTRY_POINT 

ESCAPE 

EVENT 

EXCEPTION 

EXECUTE 

EXISTS 

EXIT 

EXTERN 

EXTERNAL 

EXTRACT 

FETCH 

FILE 

FILTER 

FLOAT 

FOR 

FOREIGN 

FOUND 

FROM 

FULL 

FUNCTION 

GDSCODE 

GENERATOR 

GENJD 

GLOBAL 

GOTO 


GRANT 

GROUP 

GROUP_COMMIT_WAIT 

G ROU P_COMM IT_WAIT_TI M E 

HAVING 

HELP 

IF 

IMMEDIATE 

IN 

INACTIVE 

INDEX 

INDICATOR 

INIT 

INNER 

INPUT 

INPUT_TYPE 

INSERT 

INT 

INTEGER 

INTO 

IS 

ISOLATION 

ISOL 

JOIN 

KEY 

LC_MESSAGES 

LC_TYPE 

LEFT 

LENGTH 

LEV 

LEVEL 

LIKE 

LOGFILE 
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LOG_BUFFER_SIZE 

LOG_BUF_SIZE 

LONG 

MANUAL 

MAX 

MAXIMUM 

MAXIMUM_SEGMENT 

MAX_SEGMENT 

MERGE 

MESSAGE 

MIN 

MINIMUM 

MODULE_NAME 

NAMES 

NATIONAL 

NATURAL 

NCHAR 

NO 

NOAUTO 

NOT 

NULL 

NUMERIC 

NUM_LOG_BUFS 

NUM_LOG_BUFFERS 

OCTET_LENGTH 

OF 

ON 

ONLY 

OPEN 

OPTION 

OR 

ORDER 


OUTER 

OUTPUT 

OUTPUT_TYPE 

OVERFLOW 

PAGE 

PAGELENGTH 

PAGES 

PAGE_SIZE 

PARAMETER 

PASSWORD 

PLAN 

POSITION 

POST_EVENT 

PRECISION 

PREPARE 

PROCEDURE 

PROTECTED 

PRIMARY 

PRIVILEGES 

PUBLIC 

QUIT 

RAW_PARTITIONS 

RDB$DB_KEY 

READ 

REAL 

RECORD_VERSION 

REFERENCES 

RELEASE 

RESERV 

RESERVING 

RETAIN 

RETURN 


RETURNING_VALUES 

RETURNS 

REVOKE 

RIGHT 

ROLLBACK 

RUNTIME 

SCHEMA 

SEGMENT 

SELECT 

SET 

SHADOW 

SHARED 

SHELL 

SHOW 

SINGULAR 

SIZE 

SMALLINT 

SNAPSHOT 

SOME 

SORT 

SQL 

SQLCODE 

SQLERROR 

SQLWARNING 

STABILITY 

STARTING 

STARTS 

STATEMENT 

STATIC 

STATISTICS 

SUB_TYPE 

SUM 


SUSPEND 

TABLE 

TERMINATOR 

THEN 

TO 

TRANSACTION 

TRANSLATE 

TRANSLATION 

TRIGGER 

TRIM 

UNCOMMITTED 

UNION 

UNIQUE 

UPDATE 

UPPER 

USER 

USING 

VALUE 

VALUES 

VARCHAR 

VARIABLE 

VARYING 

VERSION 

VIEW 

WAIT 

WHEN 

WHENEVER 

WHERE 

WHILE 

WITH 

WORK 

WRITE 
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APPENDIX B 


Error Codes and Messages 


This appendix summarizes InterBase error-handling options and error codes. 
Tables in this appendix list SQLCODE and InterBase error codes and messages 
for embedded SQL, d5mamic SQL (DSQL), and interactive SQL (isql). Lor a 
detailed discussion of error handling, see the Programmer's Guide. 


Error Sources 



Run-time errors occur at points of user input or program output. When you run 
a program or use isql, the following types of errors may occur: 

Error Type 

Description 

Action 

Database error 

Bugcheck or 
internal error 

Database errors can result from any one 
of many problems, such as conversion 
errors, arithmetic exceptions, and 
validation errors. 

Bugchecks reflect software problems you 
should report. 

If you encounter one of these messages: 

• Check any messages. 

• Check the file name or path name and 
try again. 

If you encounter a bugcheck, execute a 
traceback and save the output. Submit 
output and script along with a copy of the 
database to Borland International, Inc. 



Error Repotting and Handling 


Lor reporting and dealing with errors, InterBase utilizes the SQLCQDL variable 
and InterBase codes returned in the status array. 

Every executable SQL statement sets the SQLCQDL variable, which can serve as 
a status indicator. During preprocessing, gpre declares this variable automati¬ 
cally. An application can test for and use the SQLCQDL variable in one of three 
ways: 
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• Use the WHENEVER statement to check the value of SQLCODE and 
direct the program to branch to error-handling routines coded in the 
application. 

• Test for SQLCODE directly. 

• Combine WHENEVER and direct SQLCODE testing. 

Eor SQL programs that must be portable between InterBase and other database 
management systems, limit error-handling routines to one of these methods. 

The InterBase status array displays information about errors that supplements 
SQLCODE messages. 

InterBase applications can check both the SQLCODE message and the message 
returned in the status array. 


Trapping Errors With WHENEVER 

The WHENEVER statement traps SQL errors and warnings. WHENEVER tests 
SQLCODE return values and branches to appropriate error-handling routines in 
the application. Error routines can range from: 

• Simple reporting of errors and transaction rollback, or a prompt to the 
user to reenter a query or data. 

• More sophisticated routines that react to many possible error conditions 
in predictable ways. 

WHENEVER helps limit the size of an application, since it can call on a single 
suite of routines for handling errors and warnings. 


Checking SQLCODE Value Directly 

Applications can test directly for a particular SQLCQDE after each SQL state¬ 
ment. If that SQLCQDE occurs, the program can branch to a specific routine. 

To handle specific error situations, combine checking for SQLCQDE with gen¬ 
eral WHENEVER statements. These steps outline the procedure, which is 
described in detail in the Programmer's Guide: 

1. Qverride the WHENEVER branching by inserting a WHENEVER 
SQLERRQR CQNTINUE statement. The program now ignores 
SQLCQDE. 

2. Use an SQLCQDE-checking statement to check for a particular 
SQLCQDE and direct the program to an alternative procedure. 
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3. To return to WHENEVER branching, insert a new WHENEVER 
statement. 

Where portability is not an issue, additional information may be available in the 
InterBase status array 


InterBase Status Array 

Since each SQLCODE value can result from more than one t 5 ^e of error, the 
InterBase status array (isc_status) provides additional messages that enable fur¬ 
ther inquiry into SQLCODE errors. 

gpre automatically declares isc_status, an array of twenty 32-bit integers, for all 
InterBase applications during preprocessing. When an error occurs, the status 
array is loaded with InterBase error codes, message string addresses, and some¬ 
times other numeric, interpretive, platform-specific error data. 

This appendix lists all status array codes in "SQL Error Codes and Messages." 
To see the codes online, display the ibase.h file. The location of this file is system- 
specific. 


Access to Status Array Messages 

InterBase provides library functions to retrieve and print status array codes and 
messages. 

isc_print_sqlerror() 

When SQLCQDE < 0, this function prints the returned SQLCQDE value, the cor¬ 
responding SQL error message, and any additional InterBase error messages in 
the status array to the screen. Use within an error-handling routine. 

Syntax isc_print_sqlerror (short SQLCODE, ISC_STATUS *status_vector); 

isc_sqLinterprete() 

This function retrieves an SQL error message and stores it in a user-supplied 
buffer for later printing, manipulation, or display. Allow a buffer length of 256 
bytes to hold the message. Use when building error display routines or if you 
are using a windowing system that does not permit direct screen writes. Do not 
use this function when SQLCQDE > 0. 

Syntax isc_sql_interprete(short SQLCODE, char *buffer, short length); 
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Action to Take for InterBase Error Codes 

After any error occurs, you have the following options: ignore the error, log the 
error and continue processing, roll back the transaction and try again, or roll 
back the transaction and quit the application. 

For the following errors, it is recommended that you roll back the current trans¬ 
action and try the operation again: 


Table B-1: Status Array Codes that Require Rollback and Retry 


Status Array Code 

Action to Take 

isc_convert_error 

Conversion error: A conversion between data types failed; 
correct the input and retry the operation. 

isc_deadlock 

Deadlock: Transaction conflicted with another transaction. 
Wait and try again. 

iscjntegjail 

Integrity check: Operation failed due to a trigger. Examine the 
abort code, fix the error, and try again. 

iscjockconflict 

Lock conflict: Transaction unable to obtain the locks it 
needed. Wait and try again. 

isc_no_dup 

Duplicate index entry: Attempt to add a duplicate field. Cor¬ 
rect field with duplicate and try again. 

isc_not_valid 

Validation error: Row did not pass validation test. Correct 
invalid row and try again. 


For More Information 

The following table is a guide to further information on planning and program¬ 
ming error-handling routines. 


Table B-2: Where to Find Error-handling Topics 

Topic To Find ... 


SQLCODE and error Complete discussion and programming Programmer’s Guide 


handling 
List of SQLCODEs 

WHENEVER 

syntax 

Programming 

WHENEVER 


instructions 

SQLCODEs and associated messages This Appendix: 


“SQLCODE Codes and Messages’’ 
Chapter 2: 


for embedded SQL, DSQL, isql 
Usage and syntax 

“SQL Statement Definitions’ 

Using and programming error-handling Programmer’s Guide 
routines 
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Table B-2: Where to Find Error-handling Topics (Continued) 


Topic 

To Find ... 

See... 

InterBase status array 
and functions 

Complete programming instructions 

Programmer’s Guide 

List of status array codes 

Status array error codes and 

This Appendix: 


associated messages for embedded 

“InterBase Status Array Error Codes 


SQL, DSQL, isql 

for SQL” 


SQLCODE Error Codes and Messages 

This section lists SQLCODE error codes and associated messages in the follow¬ 
ing tables: 

• SQLCODE Error Messages Summary 

• SQLCODE Codes and Messages 


SQLCODE Error Messages Summary 

This table summarizes the t 5 rpes of messages SQLCQDE can pass to a program: 

Table B-3: 

SQLCQDE and Messages Summary 

SQLCODE 

Message 

Meaning 

<0 

SQLERRQR 

Error. The statement did not complete. Table B-4 lists 
SQLCQDE error numbers and messages. 

0 

SUCCESS 

Successful completion. 

-1-1-99 

SQLWARNING 

System warning or informational message. 

-1-100 

NQT FQUND 

No qualifying records found. End of file. 


SQLCODE Codes and Messages 

The following table lists SQLCODEs and associated messages for SQL and 
DSQL. Some SQLCODE values have more than one text message associated 
with them. In these cases, InterBase returns the most relevant string message for 
the error that occurred. 

When code messages include the name of a database object or object t 5 rpe, the 
name is represented by a code in the SQLCODE Text column: 

• <string>: String value, such as the name of a database object or object 
type. 
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<long>: Long integer value, such as the identification number or code of 
a database object or object t 5 ^e. 

<digit>: Integer value, such as the identification number or code of a 
database object or object t 5 ^e. 

The InterBase number in the right-hand column is the actual error num¬ 
ber returned in the error status vector. You can use InterBase error¬ 
handling functions to report messages based on these numbers instead 
of SQL code, but doing so results in non-portable SQL programs. 


Table B-4: SQLCODE Codes and Messages 

SQLCODE SQLCODE Text 


InterBase 

Number 


To?" 

100 

100 

100 

100 


-103 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 

-104 


segment buffer length shorter than expected 
no match for first value expression 
Invalid database key 

attempted retrieval of more segments than exist 
attempt to fetch past the last record In a record stream 
table/procedure has non-SQL security class defined 
column has non-SQL security class defined 
procedure <string> does not return any values 
Data type for constant unknown 
invalid request BLR at offset <long> 


335544366L 
335544338L 
335544354L 
335544367L 
335544374L 
335544554L 
335544555L 
335544668L 
335544571L 
335544343L 


BLR syntax error: expected <string> at offset <long>, encountered <long> 335544390L 


context already in use (BLR error) 
context not defined (BLR error) 
bad parameter number 

invalid slice description language at offset <long> 
Invalid command 
Internal error 

Qption specified more than once 

Unknown transaction option 

Invalid array reference 

Token unknown - line <long>, char <long> 

Unexpected end of command 

Token unknown 


335544425L 
335544426L 
335544429L 
335544440L 
335544456L 
335544570L 
335544579L 
335544590L 
335544591L 
335544592L 
335544634L 
335544608L 
335544612L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-150 

-150 

-150 

-150 

-151 

-155 

-157 

-158 

-162 

-170 

-170 

-171 

-171 

-171 

-172 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 

-204 


attempted update of read-only table 
cannot update read-only view <string> 
not updatable 

Cannot define constraints on views 

attempted update of read-only column 

<string> is not a valid base table of the specified view 

must specify column name for view select expression 

number of columns does not match select list 

dbkey not available for multi-table views 

parameter mismatch for procedure <string> 

External functions cannot have more thanlO parameters 
function <string> could not be matched 

column not array or invalid dimensions (expected <long>, encountered 
<long>) 

Return mode by value not allowed for this data type 
function <string> is not defined 
generator <string> is not defined 
reference to invalid stream number 
CHARACTER SET <string> is not defined 
procedure <string> is not defined 
status code <string> unknown 
exception <string> not defined 

Name of Referential Constraint not defined in constraints table, 
could not find table/procedure for GRANT 
Implementation of text subtype <digit> not located. 

Data type unknown 
Table unknown 
Procedure unknown 
COLLATION <string> is not defined 

COLLATION <stnng> is not valid for specified CHARACTER SET 
Trigger unknown 

alias <string> conflicts with an alias in the same statement 


335544360L 
335544362L 
335544446L 
335544546L 
335544359L 
335544658L 
335544598L 
335544599L 
335544685L 
335544512L 
335544619L 
335544439L 
335544458L 

335544618L 
335544438L 
335544463L 
335544502L 
335544509L 
335544511L 
335544515L 
335544516L 
335544532L 
335544551L 
335544568L 
335544573L 
335544580L 
335544581L 
335544588L 
335544589L 
335544595L 
335544620L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-204 

-204 

-204 

-204 

-204 

-204 

-205 

-205 

-206 

-206 

-206 

-208 

-219 

-230 

-231 

-232 

-233 

-234 

-235 

-236 

-237 

-238 

-239 

-239 

-239 

-239 

-240 

-241 

-242 

-243 

-244 

-245 


alias <string> conflicts with a procedure in the same statement 
alias <string> conflicts with a table in the same statement 
there is no alias or table named <string> at this scope level 
there is no index <string> for table <string> 

Invalid use of CHARACTER SET or COLLATE 

BLOB SUB TYPE <string> is not defined 

column <string> is not defined in table <string> 

could not find column for GRANT 

Column unknown 

Column is not a BLOB 

Subselect illegal in this context 

invalid ORDER BY clause 

table <string> is not defined 

WAL Writer error 

Log file header of <string> too small 
Invalid version of log file <string> 

Log file <string> not latest in the chain but open flag still set 

Log file <string> not closed properly; database recovery may be required 

Database name in the log file <string> is different 

Unexpected end of log file <string> at offset <long> 

Incomplete log record at offset <long> in log file <string> 

Log record header too small at offset <long> in log file <string> 

Log block too small at offset <long> in log file <string> 

Cache length too small 

Log size too small 

Log partition size too small 

Illegal attempt to attach to an uninitialized WAL segment for <string> 
Invalid WAL parameter block option <string> 

Cannot roll over to the next log file <string> 
database does not use Write-ahead Log 
WAL subsystem encountered error 
WAL subsystem corrupted 


335544621L 
335544622L 
335544635L 
335544636L 
335544640L 
335544662L 
335544396L 
335544552L 
335544578L 
335544587L 
335544596L 
335544617L 
335544395L 
335544487L 
335544488L 
335544489L 
335544490L 
335544491L 
335544492L 
335544493L 
335544494L 
335544495L 
335544496L 
335544691L 
335544693L 
335544694L 
335544497L 
335544498L 
335544499L 
335544500L 
335544503L 
335544504L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-246 

-247 

-248 

-249 

-250 

-251 

-252 

-253 

-254 

-255 

-257 

-258 

-259 

-260 

-260 

-261 

-261 

-281 

-282 

-282 

-282 

-282 

-283 

-284 

-291 

-292 

-293 

-294 

-295 

-296 


Database <string>: WAL subsystem bug for pid <digit>\ 

Could not expand the WAL segment for database <string> 

Unable to roll over; please see InterBase log. 

WAL I/O error. Please see InterBase log. 

WAL writer - Journal server communication error. Please see InterBase 


log. 


335544513L 
335544514L 
335544521L 
335544522L 
335544523L 


WAL buffers cannot be increased. Please see InterBase log. 

WAL setup error. Please see InterBase log. 

WAL writer synchronization error for the database <string> 

Cannot start WAL writer for the database <string> 

Write-ahead Log without shared cache configuration not allowed 
WAL defined; Cache Manager must be started first 
Overflow log specification required for round-robin log 
Write-ahead Log with shadowing configuration not allowed 
Cache redefined 
Log redefined 

Partitions not supported in series of log file specification 
Total length of a partitioned log must be specified 
table <string> is not referenced in plan 

table <string> is referenced more than once in plan; use aliases to distin¬ 
guish 


335544524L 

335544525L 

335544526L 

335544527L 

335544556L 

335544566L 

335544567L 

335544629L 

335544690L 

335544692L 

335544695L 

335544696L 

335544637L 

335544638L 


the table <string> is referenced twice; use aliases to differentiate 

table <string> is referenced twice in view; use an alias to distinguish 

view <string> has more than one base table; use aliases to distinguish 

table <stnng> is referenced in the plan but not the from list 

index <string> cannot be used in the specified plan 

Column used in a PRIMARY/UNIQUE constraint must be NOT NULL. 

Cannot update constraints (RDB$REF_CONSTRAINTS). 

Cannot update constraints (RDB$CHECK_CONSTRAINTS). 

Cannot delete CHECK constraint entry (RDB$CHECK_CONSTRAINTS) 
Cannot update constraints (RDB$RELATION_CONSTRAINTS). 
internal isc software consistency check (invalid 
RDB$CONSTRAINT_TYPE) 


335544643L 
335544659L 
335544660L 
335544639L 
335544642L 
335544531L 
335544534L 
335544535L 
335544536L 
335544545L 
335544547L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-297 

-313 

-314 

-401 

-402 

-402 

-402 

-406 

-407 

-413 

-413 

-501 

-501 

-502 

-502 

-504 

-508 

-510 

-518 

-519 

-530 

-530 

-532 

-551 

-552 

-552 

-553 

-595 

-596 

-597 


Operation violates CHECK constraint <string> on view or table 
count of column list and variable list do not match 
Cannot transliterate character between character sets 
invalid comparison operator for find operation 
attempted invalid operation on a BLOB 

BLOB and array data types are not supported for <string> operation 

data operation not supported 

subscript out of bounds 

null segment of UNIQUE KEY 

conversion error from string "<string>" 

filter not found to convert type <long> to type <long> 

invalid request handle 

Attempt to reclose a closed cursor 

Declared cursor already exists 

Attempt to reopen an open cursor 

Cursor unknown 

no current record for fetch operation 
Cursor not updatable 
Request unknown 

The PREPARE statement identifies a prepare statement with an open 
cursor 

violation of FOREIGN KEY constraint: "<string>" 

Cannot prepare a CREATE DATABASE/SCHEMA statement 

transaction marked invalid by I/O error 

no permission for <string> access to <string> <string> 

only the owner of a table may reassign ownership 

user does not have GRANT privileges for operation 

cannot modify an existing user privilege 

the current position is on a crack 

illegal operation when at beginning of stream 

Preceding file did not specify length, so <string> must include starting 

page number 


335544558L 
335544669L 
335544565L 
335544647L 
335544368L 
335544414L 
335544427L 
335544457L 
335544435L 
335544334L 
335544454L 
335544327L 
335544577L 
335544574L 
335544576L 
335544572L 
335544348L 
335544575L 
335544582L 
335544688L 

335544466L 

335544597L 

335544469L 

335544352L 

335544550L 

335544553L 

335544529L 

335544645L 

335544644L 

335544632L 


164 


Language Reference 



Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-598 

-599 

-600 

-600 

-601 

-604 

-604 

-605 

-607 

-607 

-607 

-615 

-615 

-615 

-615 

-616 

-616 

-616 

-616 

-616 

-616 

-616 

-617 

-617 

-618 

-618 

-625 

-637 

-660 

-660 

-663 


Shadow number must be a positive integer 
gen.c: node not supported 

A node name is not permitted in a secondary, shadow, cache or log file 
name 

sort error: corruption in data structure 

database or file exists 

Array declared with too many dimensions 

Illegal array dimension range 

Inappropriate self-reference of column 

unsuccessful metadata update 

cannot modify or erase a system trigger 

Array/BLOB/DATE data types not allowed in arithmetic 

lock on table <string> conflicts with existing lock 

requested record lock conflicts with existing lock 

cannot drop log file when journaling is enabled 

refresh range number <long> already in use 

Cannot delete PRIMARY KEY being used in FOREIGN KEY definition. 

Cannot delete index used by an Integrity Constraint 

Cannot modify index used by an Integrity Constraint 

Cannot delete trigger used by a CHECK Constraint 

Cannot delete column being used in an Integrity Constraint. 

there are <long> dependencies 

last column in a table cannot be deleted 

Cannot update trigger used by a CHECK Constraint 

Cannot rename column being used in an Integrity Constraint. 

Cannot delete index segment used by an Integrity Constraint 

Cannot update index segment used by an Integrity Constraint 

validation error for column <string>, value "<string>" 

duplicate specification of <string> - not supported 

Non-existent PRIMARY or UNIQUE KEY specified for FOREIGN KEY. 

cannot create index <string> 

segment count of 0 defined for index <string> 


335544633L 

335544607L 

335544625L 

335544680L 
335544646L 
335544593L 
335544594L 
335544682L 
335544351L 
335544549L 
335544657L 
335544475L 
335544476L 
335544501L 
335544507L 
335544530L 
335544539L 
335544540L 
335544541L 
335544543L 
335544630L 
335544674L 
335544542L 
335544544L 
335544537L 
335544538L 
335544347L 
335544664L 
335544533L 
335544628L 
335544624L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-663 

-663 

-664 

-677 

-685 

-685 

-685 

-689 

-689 

-690 

-691 

-692 

-693 

-694 

-802 

-803 

-803 

-804 

-804 

-804 

-804 

-806 

-807 

-808 

-809 

-810 

-811 

-816 

-817 

-817 


too many keys defined for index <string> 

too few key coiumns found for index <string> (incorrect column name?) 
key size exceeds impiementation restriction for index "<string>" 

<string> extension error 

invalid BLOB type for operation 

attempt to index BLOB column in index <string> 

attempt to index array column in index <string> 

page <long> is of wrong type (expected <long>, found <long>) 

wrong page type 

segments not allowed in expression index <string> 

new record size of <long> bytes is too big 

maximum indexes per table {<digit>) exceeded 

Too many concurrent executions of the same request 

cannot access column <string> in view <string> 

arithmetic exception, numeric overflow, or string truncation 

attempt to store duplicate value (visible to active transactions) in unique 

index "<string>” 


335544631L 
335544672L 
335544434L 
335544445L 
335544465L 
335544670L 
335544671L 
335544403L 
335544650L 
335544679L 
335544681L 
335544477L 
335544663L 
335544684L 
335544321L 
335544349L 


violation of PRIMARY or UNIQUE KEY constraint: "<string>" 
wrong number of arguments on call 

SQLDA missing or incorrect vresion, or incorrect number/type of variables 
Count of columns not equal count of values 
Function unknown 

Only simple column names permitted for VIEW WITH CHECK OPTION 
No where clause for VIEW WITH CHECK OPTION 
Only one table allowed for VIEW WITH CHECK OPTION 
DISTINCT, GROUP or HAVING not permitted for VIEW WITH CHECK 
OPTION 

No subqueries permitted for VIEW WITH CHECK OPTION 
multiple rows in singleton select 
external file could not be opened for output 
attempted update during read-only transaction 
attempted write to read-only BLOB 


335544665L 
335544380L 
335544583L 
335544584L 
335544586L 
335544600L 
335544601L 
335544602L 
335544603L 

335544605L 
335544652L 
335544651L 
335544361L 
335544371L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-817 operation not supported 

-820 metadata is obsolete 

-820 unsupported on-disk structure for file <string>\ found <long>, support 
<long> 

-820 wrong DYN version 

-820 minor version too high found <long> expected <long> 

-823 invalid bookmark handle 

-824 invalid lock level <digit> 

-825 invalid lock handle 

-826 Invalid statement handle 

-827 invalid direction for find operation 

-828 invalid key position 

-829 invalid column reference 

-830 column used with aggregate 

-831 Attempt to define a second PRIMARY KEY for the same table 

-832 FOREIGN KEY column count does not match PRIMARY KEY 

-833 expression evaluation not supported 

-834 refresh range number <long> not found 

-835 bad checksum 

-836 exception <digit> 

-837 restart shared cache manager 

-838 database <string> shutdown in <digit> seconds 

-839 journal file wrong format 

-840 intermediate journal file full 

-841 too many versions 

-842 Precision should be greater than 0 

-842 Scale cannot be greater than precision 

-842 Short integer expected 

-842 Long integer expected 

-842 Unsigned short integer expected 

-901 invalid database key 

-901 unrecognized database parameter block 


335544444L 

335544356L 

335544379L 

335544437L 
335544467L 
335544473L 
335544474L 
335544519L 
335544585L 
335544655L 
335544678L 
335544616L 
335544615L 
335544548L 
335544604L 
335544606L 
335544508L 
335544649L 
335544517L 
335544518L 
335544560L 
335544686L 
335544687L 
335544677L 
335544697L 
335544698L 
335544699L 
335544700L 
335544701L 
335544322L 
335544326L 
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Table B-4: 

SQLCODE Codes and Messages (Continued) 


SQLCODE SQLCODE Text 

InterBase 

Number 

-901 

invalid BLOB handle 

335544328L 

-901 

invalid BLOB ID 

335544329L 

-901 

invalid parameter in transaction parameter block 

335544330L 

-901 

invalid format for transaction parameter block 

335544331L 

-901 

invalid transaction handle (expecting explicit transaction start) 

335544332L 

-901 

attempt to start more than <long> transactions 

335544337L 

-901 

information type inappropriate for object specified 

335544339L 

-901 

no information of this type available for object specified 

335544340L 

-901 

unknown information item 

335544341L 

-901 

action cancelled by trigger {<long>) to preserve data integrity 

335544342L 

-901 

lock conflict on no wait transaction 

335544345L 

-901 

program attempted to exit without finishing database 

335544350L 

-901 

transaction is not in limbo 

335544353L 

-901 

BLOB was not closed 

335544355L 

-901 

cannot disconnect database with open transactions {<long> active) 

335544357L 

-901 

message length error (encountered <long>, expected <long>) 

335544358L 

-901 

no transaction for request 

335544363L 

-901 

request synchronization error 

335544364L 

-901 

request referenced an unavailable database 

335544365L 

-901 

attempted read of a new, open BLOB 

335544369L 

-901 

attempted action on blob outside transaction 

335544370L 

-901 

attempted reference to BLOB in unavailable database 

335544372L 

-901 

table <string> was omitted from the transaction reserving list 

335544376L 

-901 

request includes a DSRI extension not supported in this implementation 

335544377L 

-901 

feature is not supported 

335544378L 

-901 

<string> 

335544382L 

-901 

unrecoverable conflict with limbo transaction <long> 

335544383L 

-901 

internal error 

335544392L 

-901 

database handle not zero 

335544407L 

-901 

transaction handle not zero 

335544408L 

-901 

transaction in limbo 

335544418L 

-901 

transaction not in limbo 

335544419L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 

-901 transaction outstanding 

-901 undefined message number 

-901 blocking signal has been received 

-901 database system cannot read argument <long> 

-901 database system cannot write argument <long> 

-901 <string> 

-901 transaction <long> is <string> 

-901 invalid statement handle 

-901 lock time-out on wait transaction 

-901 invalid service handle 

-901 wrong version of service parameter block 

-901 unrecognized service parameter block 

-901 service <string> is not defined 

-901 INDEX <string> 

-901 EXCEPTION <string> 

-901 COLUMN <string> 

-901 union not supported 

-901 Unsupported DSQL construct 

-901 Illegal use of keyword VALUE 

-901 TABLE <string> 

-901 PROCEDURE <string> 

-901 Specified domain or source column does not exist 

-901 variable <stnng> conflicts with parameter in same procedure 

-901 server version too old to support all CREATE DATABASE options 
-901 cannot delete 

-901 sort error 

-902 internal isc software consistency check {<string>) 

-902 database file appears corrupt (<string>) 

-902 I/O error during "<string>" operation for file "<string>" 

-902 corrupt system table 

-902 operating system directive <string> failed 

-902 internal error 


335544420L 
335544428L 
335544431L 
335544442L 
335544443L 
335544450L 
335544468L 
335544485L 
33554451OL 
335544559L 
335544561L 
335544562L 
335544563L 
335544609L 
33554461 OL 
335544611L 
335544613L 
335544614L 
335544623L 
335544626L 
335544627L 
335544641L 
335544656L 
335544666L 
335544673L 
335544675L 
335544333L 
335544335L 
335544344L 
335544346L 
335544373L 
335544384L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 

-902 internal error 

-902 internal error 

-902 block size exceeds implementation restriction 

-902 incompatible version of on-disk structure 

-902 internal error 

-902 internal error 

-902 internal error 

-902 internal error 

-902 internal error 

-902 internal error 

-902 database corrupted 

-902 checksum error on database page <long> 

-902 index is broken 

-902 transaction-request mismatch (synchronization error) 

-902 bad handle count 

-902 wrong version of transaction parameter block 

-902 unsupported BLR version (expected <long>, encountered <long>) 

-902 wrong version of database parameter block 

-902 database corrupted 

-902 internal error 

-902 internal error 

-902 internal error 

-902 internal error 

-902 lock manager error 

-902 SQL error code = <long> 

-902 

-902 

-902 cache buffer for page <long> Invalid 

-902 there is no index in table <string> with id <digit> 

-902 Your user name and password are not defined. Ask your database 
administrator to set up an InterBase login. 

-902 enable journal for database before starting online dump 


335544385L 
335544387L 
335544388L 
335544394L 
335544397L 
335544398L 
335544399L 
335544400L 
335544401L 
335544402L 
335544404L 
335544405L 
335544406L 
335544409L 
33554441OL 
335544411L 
335544412L 
335544413L 
335544415L 
335544416L 
335544417L 
335544422L 
335544423L 
335544432L 
335544436L 
335544448L 
335544449L 
335544470L 
335544471L 
335544472L 

335544478L 
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Table B-4: SQLCODE Codes and Messages (Continued) 


InterBase 

Number 


SQLCODE SQLCODE Text 


-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-902 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 

-904 


online dump failure. Retry dump 

an online dump is already in progress 

no more disk/tape space. Cannot continue oniine dump 

journaling allowed only if database has Write-ahead Log 

maximum number of online dump fiies that can be specified is 16 

error in opening Write-ahead Log file during recovery 

Write-ahead log subsystem failure 

must specify archive file when enabling long term journal for databases 

with round-robin log files 

database <string> shutdown in progress 

long-term journaling already enabled 

database <string> shutdown 

database shutdown unsuccessful 

cannot attach to password database 

cannot start transaction for password database 

long-term journaling not enabled 

Dynamic SQL Error 

invalid database handle (no active connection) 

unavailable database 

Implementation limit exceeded 

too many requests 

buffer exhausted 

buffer in use 

request in use 

no lock manager available 

unable to allocate memory from operating system 

update conflicts with concurrent update 

object <string> is in use 

cannot attach active shadow file 

a file in manual shadow <long> is unavailable 

cannot add index, index root page is full. 

sort error: not enough memory 


335544479L 
335544480L 
335544481L 
335544482L 
335544483L 
335544484L 
335544486L 
335544505L 

335544506L 
335544520L 
335544528L 
335544557L 
335544653L 
335544654L 
335544564L 
335544569L 
335544324L 
335544375L 
335544381L 
335544386L 
335544389L 
335544391L 
335544393L 
335544424L 
335544430L 
335544451L 
335544453L 
335544455L 
335544460L 
335544661L 
335544676L 
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Table B-4: 

SQLCODE Codes and Messages (Continued) 


SQLCODE SQLCODE Text 

InterBase 

Number 

-904 

request depth exceeded. (Recursive definition?) 

335544683L 

-906 

product <string> is not licensed 

335544452L 

-909 

drop database completed with errors 

335544667L 

-911 

record from transaction <long> is stuck in limbo 

335544459L 

-913 

deadlock 

335544336L 

-922 

file <string> is not a valid database 

335544323L 

-923 

connection rejected by remote interface 

335544421L 

-923 

secondary server attachments cannot validate databases 

335544461L 

-923 

secondary server attachments cannot start journaling 

335544462L 

-923 

secondary server attachments cannot start logging 

335544464L 

-924 

bad parameters on attach or create database 

335544325L 

-924 

communication error with journal "<string>" 

335544433L 

-924 

database detach completed with errors 

335544441L 

-924 

Connection lost to pipe server 

335544648L 

-926 

no rollback performed 

335544447L 

-999 

InterBase error 

335544689L 


InterBase Status Array Error Codes 

This section lists InterBase error codes and associated messages returned in the 
status array in the following tables. When code messages include the name of a 
database object or object t 5 ^e, the name is represented by a code in the Message 
column: 

• <string>: String value, such as the name of a database object or object 
type. 

• <digit>: Integer value, such as the identification number or code of a 
database object or object t 5 ^e. 
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• <long>: Long integer value, such as the identification number or code of 
a database object or object t 5 ^e. 

The following table lists SQL Status Array codes for embedded SQL programs, 
DSQL, and isql. 


Table B-5: InterBase Status Array Error Codes 


Error Code 

Number 

Message 

lsc_arlth_except 

335544321L 

arithmetic exception, numeric overflow, or string 
truncation 

lsc_bad_dbkey 

335544322L 

invalid database key 

lsc_bad_db_format 

335544323L 

file <string> is not a valid database 

lsc_bad_db_handle 

335544324L 

invalid database handle (no active connection) 

lsc_bad_dpb_content 

335544325L 

bad parameters on attach or create database 

lsc_bad_dpb_form 

335544326L 

unrecognized database parameter block 

lsc_bad_req_handle 

335544327L 

invalid request handle 

lsc_bad_segstr_handle 

335544328L 

invalid BLOB handle 

lsc_bad_segstr_ld 

335544329L 

invalid BLOB ID 

lsc_bad_tpb_content 

335544330L 

invalid parameter in transaction parameter block 

lsc_bad_tpb_form 

335544331L 

invalid format for transaction parameter block 

lsc_bad_trans_handle 

335544332L 

invalid transaction handle (expecting explicit transaction 
start) 

lsc_bug_check 

335544333L 

internal isc software consistency check {<string>) 

lsc_convert_error 

335544334L 

conversion error from string "<string>" 

lsc_db_corrupt 

335544335L 

database file appears corrupt (<string>) 

lsc_deadlock 

335544336L 

deadlock 

lsc_excess_trans 

335544337L 

attempt to start more than <long> transactions 

lsc_from_no_match 

335544338L 

no match for first value expression 

Iscjnfinap 

335544339L 

information type inappropriate for object specified 

Iscjnfona 

335544340L 

no information of this type available for object specified 

Iscjnfunk 

335544341L 

unknown information item 

Iscjntegjall 

335544342L 

action cancelled by trigger {<long>) to preserve data 
integrity 

lsc_invalld_blr 

335544343L 

invalid request BLR at offset <long> 

lsc_io_error 

335544344L 

I/O error during "<string>" operation for file "<string>" 

Iscjockconflict 

335544345L 

lock conflict on no wait transaction 

lsc_metadata_corrupt 

335544346L 

corrupt system table 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code Number Message 


lsc_not_valid 

335544347L 

validation error for column <string>, value "<string>" 

lsc_no_cur_rec 

335544348L 

no current record for fetch operation 

lsc_no_dup 

335544349L 

attempt to store duplicate value (visible to active trans¬ 
actions) in unique index "<string>" 

lsc_no_flnlsh 

335544350L 

program attempted to exit without finishing database 

lsc_no_meta_update 

335544351L 

unsuccessful metadata update 

lsc_nojDriv 

335544352L 

no permission for <string> access to <string> <string> 

lsc_no_recon 

335544353L 

transaction is not in limbo 

lsc_no_record 

335544354L 

invalid database key 

lsc_no_segstr_close 

335544355L 

BLOB was not closed 

lsc_obsolete_metadata 

335544356L 

metadata is obsolete 

lsc_open_trans 

335544357L 

cannot disconnect database with open transactions 
{<long> active) 

lsc_port_len 

335544358L 

message length error (encountered <long>, expected 
<long>) 

lsc_read_only_fleld 

335544359L 

attempted update of read-only column 

lsc_read_only_rel 

335544360L 

attempted update of read-only table 

lsc_read_only_trans 

335544361L 

attempted update during read-only transaction 

lsc_read_only_vlew 

335544362L 

cannot update read-only view <string> 

lsc_req_no_trans 

335544363L 

no transaction for request 

lsc_req_sync 

335544364L 

request synchronization error 

lsc_req_wrong_db 

335544365L 

request referenced an unavailable database 

lsc_segment 

335544366L 

segment buffer length shorter than expected 

lsc_segstr_eof 

335544367L 

attempted retrieval of more segments than exist 

lsc_segstr_no_op 

335544368L 

attempted invalid operation on a BLOB 

lsc_segstr_no_read 

335544369L 

attempted read of a new, open BLOB 

lsc_segstr_no_trans 

335544370L 

attempted action on blob outside transaction 

lsc_segstr_no_wrlte 

335544371L 

attempted write to read-only BLOB 

lsc_segstr_wrong_db 

335544372L 

attempted reference to BLOB in unavailable database 

lsc_sys_request 

335544373L 

operating system directive <stnng> failed 

lsc_stream_eof 

335544374L 

attempt to fetch past the last record in a record stream 

lsc_unavallable 

335544375L 

unavailable database 

lsc_unres_rel 

335544376L 

table <string> was omitted from the transaction reserv¬ 
ing list 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

lsc_uns_ext 

335544377L 

request includes a DSRI extension not supported In this 
Implementation 

lsc_wlsh_llst 

335544378L 

feature Is not supported 

lsc_wrong_ods 

335544379L 

unsupported on-dlsk structure for file <string>-, found 
<long>, support <long> 

lsc_wronumarg 

335544380L 

wrong number of arguments on call 

Iscjmpexc 

335544381L 

Implementation limit exceeded 

lsc_random 

335544382L 

<string> 

lsc_fatal_conflict 

335544383L 

unrecoverable conflict with limbo transaction <long> 

lsc_badblk 

335544384L 

internal error 

Iscjnvpoolcl 

335544385L 

internal error 

lsc_nopoolids 

335544386L 

too many requests 

lsc_relbadblk 

335544387L 

internal error 

lsc_blktoobig 

335544388L 

block size exceeds implementation restriction 

lsc_bufexh 

335544389L 

buffer exhausted 

lsc_syntaxerr 

335544390L 

BLR syntax error: expected <string> at offset <long>, 
encountered <long> 

lsc_buflnuse 

335544391L 

buffer in use 

lsc_bdblncon 

335544392L 

internal error 

lsc_reqlnuse 

335544393L 

request in use 

lsc_badodsver 

335544394L 

incompatible version of on-disk structure 

lsc_relnotdef 

335544395L 

table <string> is not defined 

IscJIdnotdef 

335544396L 

column <string> is not defined in table <string> 

lsc_dirtypage 

335544397L 

internal error 

lsc_waifortra 

335544398L 

internal error 

lsc_doubleloc 

335544399L 

internal error 

lsc_nodnotfnd 

335544400L 

internal error 

lsc_dupnodfnd 

335544401L 

internal error 

Iscjocnotmar 

335544402L 

internal error 

lsc_badpagtyp 

335544403L 

page <long> is of wrong type (expected <long>, found 
<long>) 

lsc_corrupt 

335544404L 

database corrupted 

lsc_badpage 

335544405L 

checksum error on database page <long> 

lsc_badlndex 

335544406L 

index is broken 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

lsc_dbbnotzer 

335544407L 

database handle not zero 

lsc_tranotzer 

335544408L 

transaction handle not zero 

lsc_trareqmls 

335544409L 

transaction-request mismatch (synchronization error) 

lsc_badhndcnt 

33554441OL 

bad handle count 

lsc_wrotpbver 

335544411L 

wrong version of transaction parameter block 

lsc_wroblrver 

335544412L 

unsupported BLR version (expected <long>, encoun¬ 
tered <long>) 

lsc_wrodpbver 

335544413L 

wrong version of database parameter block 

lsc_blobnotsup 

335544414L 

BLOB and array data types are not supported for 
<string> operation 

lsc_badrelatlon 

335544415L 

database corrupted 

lsc_nodetach 

335544416L 

internal error 

lsc_notremote 

335544417L 

internal error 

lsc_trainllm 

335544418L 

transaction in limbo 

lsc_notlnlim 

335544419L 

transaction not in limbo 

lsc_traoutsta 

335544420L 

transaction outstanding 

lsc_connect_reject 

335544421L 

connection rejected by remote interface 

lsc_dbflle 

335544422L 

internal error 

lsc_orphan 

335544423L 

internal error 

lsc_no_lock_mgr 

335544424L 

no lock manager available 

lsc_ctxinuse 

335544425L 

context already in use (BLR error) 

lsc_ctxnotdef 

335544426L 

context not defined (BLR error) 

lsc_datnotsup 

335544427L 

data operation not supported 

lsc_badmsgnum 

335544428L 

undefined message number 

lsc_badparnum 

335544429L 

bad parameter number 

lsc_virmemexh 

335544430L 

unable to allocate memory from operating system 

lsc_blocklng_slgnal 

335544431L 

blocking signal has been received 

Iscjockmanerr 

335544432L 

lock manager error 

Iscjournerr 

335544433L 

communication error with journal "<string>” 

lsc_keytooblg 

335544434L 

key size exceeds implementation restriction for index 
"<string>" 

lsc_nullsegkey 

335544435L 

null segment of UNIQUE KEY 

lsc_sqlerr 

335544436L 

SQL error code = <long> 


176 


Language Reference 




Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 


Number Message 


lsc_wrodynver 

Iscjunnotdef 

lsc_funmlsmat 

lsc_bad_msg_vec 

lsc_bad_detach 

lsc_noargacc_read 

lsc_noargacc_write 

lsc_read_only 

lsc_ext_err 

lsc_non_updatable 

lsc_no_rollback 

lsc_bad_sec_info 

lsc_invalld_sec_lnfo 

lsc_mlsc_interpreted 

lsc_update_conflict 

lsc_unlicensed 

lsc_obj_in_use 

lsc_nofllter 

lsc_shadow_accessed 

lsc_invalld_sdl 

lsc_out_of_bounds 

lsc_invalld_dimension 

lsc_rec_in_llmbo 

lsc_shadow_mlsslng 

lsc_cant_validate 

lsc_cant_startJournal 

lsc_gennotdef 

lsc_cant_start_logglng 

lsc_bad_segstr_type 

lsc_foreign_key 

lsc_high_minor 


335544437L 
335544438L 
335544439L 
335544440L 
335544441L 
335544442L 
335544443L 
335544444L 
335544445L 
335544446L 
335544447L 
335544448L 
335544449L 
335544450L 
335544451L 
335544452L 
335544453L 
335544454L 
335544455L 
335544456L 
335544457L 
335544458L 

335544459L 
335544460L 
335544461L 

335544462L 

335544463L 

335544464L 

335544465L 

335544466L 

335544467L 


wrong DYN version 

function <string> is not defined 

function <string> could not be matched 

database detach completed with errors 

database system cannot read argument <long> 

database system cannot write argument <long> 

operation not supported 

<string> extension error 

not updatable 

no rollback performed 


<string> 

update conflicts with concurrent update 
product <string> is not licensed 
object <string> is in use 

filter not found to convert type <long> to type <long> 
cannot attach active shadow file 
invalid slice description language at offset <long> 
subscript out of bounds 

column not array or invalid dimensions (expected 

<long>, encountered <long>) 

record from transaction <long> is stuck in limbo 

a file in manual shadow <long> is unavailable 

secondary server attachments cannot validate 

databases 

secondary server attachments cannot start journaling 

generator <string> is not defined 

secondary server attachments cannot start logging 

invalid BLOB type for operation 

violation of FOREIGN KEY constraint: "<string>" 

minor version too high found <long> expected <long> 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

lsc_tra_state 

335544468L 

transaction <long> Is <string> 

lsc_trans_lnvalld 

335544469L 

transaction marked invalid by I/O error 

lsc_buf_invalld 

335544470L 

cache buffer for page <long> invalid 

Iscjndexnotdefined 

335544471L 

there is no index in table <string> with Id <digit> 

Iscjogin 

335544472L 

Your user name and password are not defined. Ask 
your database administrator to set up an InterBase 
login. 

lsc_invalld_bookmark 

335544473L 

invalid bookmark handle 

lsc_bad_lock_level 

335544474L 

Invalid lock level <digit> 

lsc_relation_lock 

335544475L 

lock on table <string> conflicts with existing lock 

lsc_record_lock 

335544476L 

requested record lock conflicts with existing lock 

lsc_max_idx 

335544477L 

maximum indexes per table {<digit>) exceeded 

Iscjrnenable 

335544478L 

enable journal for database before starting online dump 

lsc_old_fallure 

335544479L 

online dump failure. Retry dump 

lsc_old_in_progress 

335544480L 

an online dump is already in progress 

lsc_old_no_space 

335544481L 

no more disk/tape space. Cannot continue online dump 

lsc_no_wal_noJrn 

335544482L 

journaling allowed only if database has Write-ahead 

Log 

lsc_num_old_flles 

335544483L 

maximum number of online dump files that can be spec¬ 
ified is 16 

lsc_wal_file_open 

335544484L 

error in opening Write-ahead Log file during recovery 

lsc_bad_stmt_handle 

335544485L 

invalid statement handle 

lsc_wal_fallure 

335544486L 

Write-ahead log subsystem failure 

lsc_walw_err 

335544487L 

WAL Writer error 

Iscjoghsmall 

335544488L 

Log file header of <string> too small 

Iscjoghjnvverslon 

335544489L 

Invalid version of log file <string> 

Iscjoghopenflag 

335544490L 

Log file <string> not latest in the chain but open flag still 
set 

lsc_logh_open_flag2 

335544491L 

Log file <string> not closed properly; database recovery 
may be required 

lsc_logh_diff_dbname 

335544492L 

Database name in the log file <string> is different 

lsc_logf_u nexpected_eof 

335544493L 

Unexpected end of log file <string> at offset <long> 

Iscjogrjncomplete 

335544494L 

Incomplete log record at offset <long> in log file 
<string> 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

Iscjogrheadersmall 

335544495L 

Log record header too small at offset <long> in log file 
<string> 

lsc_logb_small 

335544496L 

Log block too small at offset <long> in log file <string> 

lsc_wal_lllegal_attach 

335544497L 

Illegal attempt to attach to an uninitialized WAL seg¬ 
ment for <string> 

lsc_wal_lnvalld_wpb 

335544498L 

Invalid WAL parameter block option <string> 

lsc_wal_err_rollover 

335544499L 

Cannot roll over to the next log file <string> 

lsc_no_wal 

335544500L 

database does not use Write-ahead Log 

lsc_drop_wal 

335544501L 

cannot drop log file when journaling is enabled 

lsc_stream_not_defined 

335544502L 

reference to invalid stream number 

lsc_wal_subsys_error 

335544503L 

WAL subsystem encountered error 

lsc_wal_subsys_corrupt 

335544504L 

WAL subsystem corrupted 

lsc_no_archlve 

335544505L 

must specify archive file when enabling long-term jour¬ 
nal for databases with round-robin log files 

lsc_shutinprog 

335544506L 

database <string> shutdown in progress 

lsc_range_in_use 

335544507L 

refresh range number <long> already in use 

lsc_range_not_found 

335544508L 

refresh range number <long> not found 

lsc_charset_not_found 

335544509L 

CHARACTER SET <string> is not defined 

Iscjocktimeout 

33554451OL 

lock time-out on wait transaction 

lsc_prcnotdef 

335544511L 

procedure <string> is not defined 

lsc_prcmlsmat 

335544512L 

parameter mismatch for procedure <string> 

lsc_wal_bugcheck 

335544513L 

Database <string>: WAL subsystem bug for pid <digit>\ 

lsc_wal_cant_expand 

335544514L 

Could not expand the WAL segment for database 
<stnng> 

lsc_codnotdef 

335544515L 

status code <string> unknown 

lsc_xcpnotdef 

335544516L 

exception <string> not defined 

lsc_except 

335544517L 

exception <digit> 

lsc_cache_restart 

335544518L 

restart shared cache manager 

lsc_bad_lock_handle 

335544519L 

invalid lock handle 

IscJrnjDresent 

335544520L 

long-term journaling already enabled 

lsc_wal_err_rollover2 

335544521L 

Unable to roll over; please see InterBase log. 

lsc_wal_err_logwrlte 

335544522L 

WAL I/O error. Please see InterBase log. 

lsc_wal_errJrn_comm 

335544523L 

WAL writer - Journal server communication error. 

Please see InterBase log. 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

lsc_wal_err_expansion 

lsc_wal_err_setup 

lsc_wal_err_ww_sync 

lsc_wal_err_ww_start 

lsc_shutdown 

lsc_existlng_prlv_mod 

lsc_prlmary_key_ref 

lsc_prlmary_key_notnull 

lsc_ref_cnstrnt_notfound 

lsc_foreign_key_notfound 

lsc_ref_cnstrnt_update 

lsc_check_cnstrnt_update 

lsc_check_cnstrnt_del 

lsc_integ_lndex_seg_del 

lsc_integ_lndex_seg_mod 

Iscjntegjndexdel 

lsc_integ_lndex_mod 

lsc_check_trig_del 

lsc_check_trig_update 

lsc_cnstrnt_fld_del 

lsc_cnstrnt_fld_rename 

lsc_rel_cnstrnt_update 


Number Message 


335544524L 

335544525L 

335544526L 

335544527L 

335544528L 

335544529L 

335544530L 

335544531L 

335544532L 

335544533L 

335544534L 

335544535L 

335544536L 

335544537L 

335544538L 

335544539L 
335544540L 
335544541L 
335544542L 
335544543L 

335544544L 

335544545L 


WAL buffers cannot be Increased. Please see InterBase 
log. 

WAL setup error. Please see InterBase log. 

WAL writer synchronization error for the database 
<string> 

Cannot start WAL writer for the database <string> 

database <string> shutdown 

cannot modify an existing user privilege 

Cannot delete PRIMARY KEY being used in FOREIGN 

KEY definition. 

Column used in a PRIMARY/UNIQUE constraint must 
be NOT NULL. 

Name of Referential Constraint not defined in con¬ 
straints table. 

Non-existent PRIMARY or UNIOUE KEY specified for 
FOREIGN KEY. 

Cannot update constraints 
(RDB$REF_CONSTRAINTS). 

Cannot update constraints 
(RDB$CHECK_CONSTRAINTS). 

Cannot delete CFIECK constraint entry 
(RDB$CHECK_CONSTRAINTS) 

Cannot delete index segment used by an Integrity 
Constraint 

Cannot update index segment used by an Integrity 
Constraint 

Cannot delete index used by an Integrity Constraint 
Cannot modify index used by an Integrity Constraint 
Cannot delete trigger used by a CFIECK Constraint 
Cannot update trigger used by a CFIECK Constraint 
Cannot delete column being used in an Integrity 
Constraint. 

Cannot rename column being used in an Integrity 
Constraint. 

Cannot update constraints 
(RDB$RELATION_CONSTRAINTS). 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 


Number Message 


lsc_constalnt_on_vlew 

lsc_invld_cnstrnt_type 

lsc_prlmary_key_exists 

lsc_systrlg_update 

lsc_not_rel_owner 

lsc_grant_obj_notfound 

lsc_grant_fld_notfound 

lsc_grant_noprlv 

lsc_nonsql_security_rel 

lsc_nonsql_security_fld 

lsc_wal_cache_err 

lsc_shutfall 

lsc_check_constraint 

lsc_bad_svc_handle 

lsc_shutwarn 

lsc_wrospbver 

lsc_bad_spb_form 

lsc_svcnotdef 

lsc_noJrn 

lsc_transliteration_falled 

lsc_start_cm_for_wal 

lsc_wal_ovflow_log_requlred 

lsc_text_subtype 

lsc_dsql_error 

lsc_dsqLcommand_err 

lsc_dsql_constant_err 

lsc_dsql_cursor_err 

lsc_dsql_datatype_err 

lsc_dsql_decl_err 

lsc_dsqLcursor_update_err 


335544546L 

335544547L 

335544548L 

335544549L 
335544550L 
335544551L 
335544552L 
335544553L 
335544554L 
335544555L 
335544556L 

335544557L 

335544558L 

335544559L 
335544560L 
335544561L 
335544562L 
335544563L 
335544564L 
335544565L 
335544566L 
335544567L 
335544568L 
335544569L 
335544570L 
335544571L 
335544572L 
335544573L 
335544574L 
335544575L 


Cannot define constraints on views 

internal isc software consistency check (invalid 

RDB$CONSTRAINT_TYPE) 

Attempt to define a second PRIMARY KEY for the same 
table 

cannot modify or erase a system trigger 

only the owner of a table may reassign ownership 

could not find table/procedure for GRANT 

could not find column for GRANT 

user does not have GRANT privileges for operation 

table/procedure has non-SQL security class defined 

column has non-SQL security class defined 

Write-ahead Log without shared cache configuration not 

allowed 

database shutdown unsuccessful 

Qperation violates CHECK constraint <string> on view 

or table 

Invalid service handle 

database <string> shutdown in <digit> seconds 

wrong version of service parameter block 

unrecognized service parameter block 

service <string> is not defined 

long-term journaling not enabled 

Cannot transliterate character between character sets 

WAL defined; Cache Manager must be started first 

Qverflow log specification required for round-robin log 

Implementation of text subtype <digit> not located. 

Dynamic SQL Error 

Invalid command 

Data type for constant unknown 

Cursor unknown 

Data type unknown 

Declared cursor already exists 

Cursor not updatable 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

lsc_dsql_cursor_open_err 

335544576L 

Attempt to reopen an open cursor 

lsc_dsql_cursor_close_err 

335544577L 

Attempt to reclose a closed cursor 

lsc_dsql_fleld_err 

335544578L 

Column unknown 

lsc_dsqljnternal_err 

335544579L 

Internal error 

lsc_dsqLrelatlon_err 

335544580L 

Table unknown 

lsc_dsql_procedure_err 

335544581L 

Procedure unknown 

lsc_dsql_request_err 

335544582L 

Request unknown 

lsc_dsql_sqlda_err 

335544583L 

SQLDA missing or incorrect vresion, or incorrect num¬ 
ber/type of variabies 

lsc_dsql_var_count_err 

335544584L 

Count of coiumns not equal count of values 

lsc_dsql_stmt_handle 

335544585L 

Invalid statement handle 

lsc_dsql_function_err 

335544586L 

Function unknown 

lsc_dsql_blob_err 

335544587L 

Column is not a BLOB 

lsc_collatlon_not_found 

335544588L 

COLLATION <string> is not defined 

lsc_collatlon_not_for_charset 

335544589L 

COLLATION <string> is not valid for specified 
CHARACTER SET 

lsc_dsql_dup_optlon 

335544590L 

Option specified more than once 

lsc_dsql_tran_err 

335544591L 

Unknown transaction option 

lsc_dsqljnvalid_array 

335544592L 

Invalid array reference 

lsc_dsqLmax_arr_dim_exceede 

d 

335544593L 

Array declared with too many dimensions 

lsc_dsql_arr_range_error 

335544594L 

Illegal array dimension range 

lsc_dsql_trlgger_err 

335544595L 

Trigger unknown 

lsc_dsqLsubselect_err 

335544596L 

Subselect illegal in this context 

lsc_dsql_crdb_prepare_err 

335544597L 

Cannot prepare a CREATE DATABASE/SCHEMA 
statement 

lsc_speclfy_fleld_err 

335544598L 

must specify column name for view select expression 

lsc_num_fleld_err 

335544599L 

number of columns does not match select list 

lsc_col_name_err 

335544600L 

Only simple column names permitted for VIEW WITH 
CHECK OPTION 

lsc_where_err 

335544601L 

No WHERE clause for VIEW WITH CHECK OPTION 

lsc_table_view_err 

335544602L 

Only one table allowed for VIEW WITH CHECK 
OPTION 


182 


Language Reference 








Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

lsc_distlnct_err 

lsc_key_field_count_err 

lsc_subquery_err 

lsc_expresslon_eval_err 

lsc_node_err 

lsc_command_end_err 

Iscjndexname 

lsc_exceptlon_name 

lsc_field_name 

lsc_token_err 

lsc_union_err 

lsc_dsql_construct_err 

lsc_field_aggregate_err 

lsc_field_ref_err 

lsc_order_by_err 

lsc_return_mode_err 

lsc_extern_func_err 

lsc_allas_confllct_err 

lsc_procedure_conflict_error 

lsc_relation_conflict_err 

lsc_dsql_domaln_err 

lsc_idx_seg_err 

lsc_node_name_err 

lsc_table_name 

lsc_proc_name 

lsc_idx_create_err 


Number 

335544603L 

335544604L 

335544605L 

335544606L 
335544607L 
335544608L 
335544609L 
33554461OL 
335544611L 
335544612L 
335544613L 
335544614L 
335544615L 
335544616L 
335544617L 
335544618L 
335544619L 

335544620L 

335544621L 

335544622L 

335544623L 

335544624L 

335544625L 

335544626L 

335544627L 

335544628L 


Message 

DISTINCT, GROUP or HAVING not permitted for VIEW 
WITH CHECK OPTION 
FOREIGN KEY column count does not match 
PRIMARY KEY 

No subqueries permitted for VIEW WITH CHECK 
OPTION 

expression evaluation not supported 
gen.c: node not supported 
Unexpected end of command 
INDEX <string> 

EXCEPTION <string> 

COLUMN <string> 

Token unknown 
union not supported 
Unsupported DSQL construct 
column used with aggregate 
invalid column reference 
Invalid ORDER BY clause 

Return mode by value not allowed for this data type 
External functions cannot have more than 10 
parameters 

alias <string> conflicts with an alias in the same 
statement 

alias <string> conflicts with a procedure in the same 
statement 

alias <string> conflicts with a table in the same 
statement 

Illegal use of keyword VALUE 

segment count of 0 defined for index <string> 

A node name is not permitted in a secondary, shadow, 
cache or log file name 
TABLE <string> 

PROCEDURE <stnng> 
cannot create index <string> 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

lsc_wal_shadow_err 

lsc_dependency 

lsc_idx_key_err 

lsc_dsql_flle_length_err 

lsc_dsql_shadow_number_err 

lsc_dsqLtoken_unk_err 

lsc_dsql_no_relatlon_allas 

Iscjndexname 

lsc_no_stream_plan 

lsc_stream_twice 

lsc_stream_not_found 

lsc_collatlon_requlres_text 

lsc_dsql_domaln_not_found 

lsc_index_unused 

lsc_dsqLselfJoin 

lsc_stream_bof 

lsc_stream_crack 

lsc_db_or_flle_exlsts 

lsc_invalld_operator 

lsc_conn_lost 

lsc_bad_checksum 

lsc_page_type_err 

lsc_ext_readonly_err 

lsc_sing_select_err 

lsc_psw_attach 

lsc_psw_start_trans 

lsc_invalld_direction 


Number Message 


335544629L 

335544630L 
335544631L 
335544632L 

335544633L 

335544634L 

335544635L 

335544636L 

335544637L 

335544638L 

335544639L 

335544640L 
335544641L 
335544642L 
335544643L 

335544644L 
335544645L 
335544646L 
335544647L 
335544648L 
335544649L 
335544650L 
335544651L 
335544652L 
335544653L 
335544654L 
335544655L 


Write-ahead Log with shadowing configuration not 
allowed 

there are <long> dependencies 

too many keys defined for index <string> 

Preceding file did not specify length, so <string> must 

include starting page number 

Shadow number must be a positive integer 

Token unknown - line <long>, char <long> 

there is no alias or table named <string> at this scope 

level 

there is no index <string> for table <string> 

table <string> is not referenced in plan 

table <string> is referenced more than once in plan; use 

aliases to distinguish 

table <string> is referenced in the plan but not the from 
list 

Invalid use of CHARACTER SET or COLLATE 
Specified domain or source column does not exist 
index <string> cannot be used in the specified plan 
the table <string> is referenced twice; use aliases to 
differentiate 

illegal operation when at beginning of stream 
the current position is on a crack 
database or file exists 

invalid comparison operator for find operation 
Connection lost to pipe server 
bad checksum 
wrong page type 

external file could not be opened for output 
multiple rows In singleton select 
cannot attach to password database 
cannot start transaction for password database 
invalid direction for find operation 


184 


Language Reference 








Table B-5: InterBase Status Array Error Codes (Continued) 

Error Code Number Message 

lsc_dsql_var_conflict 335544656L variable <string> conflicts with parameter in same 

procedure 

isc_dsql_no_blob_array 335544657L Array/BLOB/DATE data types not allowed in arithmetic 

isc_dsql_base_table 335544658L <string> is not a valid base table of the specified view 

isc_duplicate_base_table 335544659L table <string> is referenced twice in view; use an alias 

to distinguish 

isc_view_alias 335544660L view <string> has more than one base table; use 

aliases to distinguish 

lsc_index_root_page_full 335544661L cannot add Index, index root page is full. 

isc_dsql_blob_type_unknown 335544662L BLOB SUB TYPE <string> is not defined 

isc_req_max_clones_exceeded 335544663L Too many concurrent executions of the same request 

isc_dsql_duplicate_spec 335544664L duplicate specification of <string> - not supported 

isc_unique_key_violation 335544665L violation of PRIMARY or UNIQUE KEY constraint: 

”<string>" 

isc_srvr_version_too_old 335544666L server version too old to support all CREATE 

DATABASE options 

lsc_drdb_completed_with_errs 335544667L drop database completed with errors 

isc_dsql_procedure_use_err 335544668L procedure <string> does not return any values 

lsc_dsql_count_mlsmatch 335544669L count of column list and variable list do not match 

isc_blob_idx_err 335544670L attempt to index BLOB column In index <string> 

isc_array_idx_err 335544671L attempt to index array column in index <stnng> 

isc_key_field_err 335544672L too few key columns found for index <string> (incorrect 

column name?) 

isc_no_delete 335544673L cannot delete 

isc_del_last_field 335544674L last column in a table cannot be deleted 

isc_sort_err 335544675L sort error 

isc_sort_mem_err 335544676L sort error: not enough memory 

isc_version_err 335544677L too many versions 

isc_inval_key_posn 335544678L invalid key position 

isc_no_segments_err 335544679L segments not allowed in expression index <string> 

isc_crrp_data_err 335544680L sort error: corruption in data structure 

isc_rec_size_err 335544681L new record size of <long> bytes is too big 

isc_dsqLfield_ref 335544682L Inappropriate self-reference of column 

isc_req_depth_exceeded 335544683L request depth exceeded. (Recursive definition?) 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 


Number Message 


lsc_no_fleld_access 

lsc_no_dbkey 

lscJrn_format_err 

iscjrnjilejull 

lsc_dsqLopen_cursor_request 

lsc_ib_error 

lsc_cache_redef 

lsc_cache_too_small 

lsc_log_redef 

lsc_log_too_small 

lsc_partitlon_too_small 

lsc_partitlon_not_supp 

Iscjogjengthspec 

lsc_precision_err 

lsc_scale_nogt 

lsc_expec_short 

lsc_expec_long 

lsc_expec_ushort 

IscJ I ke_escape_i nvalid 

lsc_svcnoexe 

lsc_net_lookup_err 

lsc_service_unknown 

lsc_host_unknown 

lsc_grant_noprlv_on_base 

lsc_dyn_fld_ambiguous 

lsc_dsql_agg_ref_err 

lsc_complex_vlew 

lsc_unprepared_stmt 

lsc_expec_posltlve 


335544684L 

335544685L 

335544686L 

335544687L 

335544688L 

335544689L 
335544690L 
335544691L 
335544692L 
335544693L 
335544694L 
335544695L 
335544696L 
335544697L 
335544698L 
335544699L 
335544700L 
335544701L 
335544702L 
335544703L 

335544704L 

335544705L 

335544706L 

335544707L 

335544708L 
335544709L 
33554471OL 

335544711L 

335544712L 


cannot access column <string> In view <string> 
dbkey not available for multi-table views 
journal file wrong format 
intermediate journal file full 

The prepare statement identifies a prepare statement 

with an open cursor 

InterBase error 

Cache redefined 

Cache length too small 

Log redefined 

Log size too small 

Log partition size too small 

Partitions not supported in series of log file specification 

Total length of a partitioned log must be specified 

Precision should be greater than 0 

Scale cannot be greater than precision 

Short integer expected 

Long integer expected 

Unsigned short integer expected 

Invalid ESCAPE sequence 

service <string> does not have an associated execut¬ 
able 

Network lookup failure for host "<string>'' 

Undefined service <string>/<string> 

Host unknown 

user does not have GRANT privileges on base table/ 
view for operation 
Ambiguous column reference. 

Invalid aggregate reference 

navigational stream <long> references a view with more 
than one base table. 

attempt to execute an unprepared dynamic SQL state¬ 
ment 

Positive value expected. 
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Table B-5: InterBase Status Array Error Codes (Continued) 


Error Code 

Number 

Message 

lsc_dsql_sqlda_value_err 

335544713L 

Incorrect values within SQLDA structure 

lsc_invalld_array_ld 

335544714L 

Invalid blob id 

lsc_ext_file_uns_op 

335544715L 

Operation not supported for EXTERNAL FILE table 
<stnng> 
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Appendix C 

System Tables and Views 


This appendix describes the InterBase system tables and SQL system views. 


Overview 


The InterBase system tables contain and track metadata. InterBase automatically 
creates system tables when a database is created. Each time a user creates or 
modifies metadata through data definition, the SQL data definition utility auto¬ 
matically updates the system tables. 

The SQL system views provide information about existing integrity constraints 
for a database. They are a subset of views defined in the SQL-92 standard. Sys¬ 
tem views are created separately by running an isql script after database 
definition. 

To see system tables, use this isql command: 

SHOW SYSTEM TABLES; 

The following isql command lists system views along with database views: 

SHOW VIEWS; 


System Tables 

This table lists the InterBase system tables. The names of system tables and their 
columns start with RDB$. 

Table C-1: System Tables 

RDB$CHARACTER_SETS RDB$LOG_FILES 

RDB$COLLATIONS RDB$PAGES 

RDB$CHECK_CONSTRAINTS RDB$PROCEDURE_PARAMETERS 

RDB$DATABASE RDB$PROCEDURES 
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Table C-1: System Tables (Continued) 


RDB$DEPENDENCIES 

RDB$REF_CONSTRAINTS 

RDB$EXCEPTIONS 

RDB$RELATION_CONSTRAINTS 

RDB$FIELD_DIMENSIONS 

RDB$RELATION_FIELDS 

RDB$FIELDS 

RDB$RELATIONS 

RDB$FILES 

RDB$SECURITY_CLASSES 

RDB$FILTERS 

RDB$TRANSACTIONS 

RDB$FORMATS 

RDB$TRIGGER_MESSAGES 

RDB$FUNCTION_ARGUMENTS 

RDB$TRIGGERS 

RDB$FUNCTIONS 

RDB$TYPES 

RDB$GENERATORS 

RDB$USER_PRIVILEGES 

RDB$INDEX_SEGMENTS 

RDB$INDICES 

RDB$VIEW_RELATIONS 


System Views 


This table lists SQL system views. Since they are not automatically defined by 
InterBase, the names of system views and their columns do not start with RDB$. 

Table C-2: System Views 


CHECK_CONSTRAINTS 

REFERENTIAL_CONSTRAINTS 

CONSTRAINTS_COLUMN_USAGE 

TABLE_CONSTRAINTS 


RDB$CHARACTER_SETS 

RDB$CHARACTER_SETS describes the valid character sets available in 
InterBase. 


Table C-3: RDB$CHARACTER_SETS 


Column Name 

Data Type Length Description 

RDB$CHARACTER SET 
NAME 

CHAR 

31 

Name of a character set that InterBase recognizes. 

RDB$FORM_OF_USE 

CHAR 

31 

Reserved for Internal use. Subtype 2. 

RDB$NUMBER OF 
CHARACTERS 

INTEGER 


Number of characters In a particular character set. For 
example, the set of Japanese characters. 

RDB$DEFAULT 

COLLATE_NAME 

CHAR 

31 

Subtype 2. Default collation sequence for the character 
set. 


190 


Language Reference 



Table C-3: RDB$CHARACTER_SETS (Continued) 


Column Name Data Type Length Description 


RDB$CHARACTER_ SMALLINT 

SETJD 

RDB$SYSTEM_FLAG SMALLINT 


RDB$DESCRIPTION BLOB 

RDB$FUNCTION_NAME CHAR 
RDB$BYTES_PER_ SMALLINT 

CHARACTER 


A unique identification for the character set. 

Indicates whether the character set is: 

• User-defined (value of 0) 

• System-defined (value of 1) 

80 Subtype text. Contains a user-written description of the 
character set. 

31 Reserved for internal use. Subtype 2. 

Size of character in bytes. 


RDB$CHECK_CONSTRAINTS 


RDB$CHECK_CONSTRAINTS stores database integrity constraint information 
for CHECK constraints. In addition, the table stores information for constraints 
implemented with NOT NULL. 


Table C-4: RDB$CHECK_CONSTRAINTS 


Column Name 

Data Type Length Description 

RDB$CONSTRAINT 

NAME 

CHAR 

31 

Subtype 2. Name of a CHECK or NOT NULL constraint. 

RDB$TRIGGER_NAME 

CHAR 

31 

Subtype 2. Name of the trigger that enforces the 

CHECK constraint. For a NOT NULL constraint, name 
of the source column in RDB$RELATION_FIELDS. 


RDB$COLLATIONS 


RDB$COLLATIONS records the valid collating sequences available for use in 
InterBase. 

Table C-5: RDB$COLLATIONS 

Column Name Data Type Length Description 

RDB$COLLATION_NAME CHAR 31 Name of a valid collation sequence in InterBase. 

RDB$COLLATION_ID SMALLINT Unique identifier for the collation sequence. 
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Table C-5: RDB$COLLATIONS (Continued) 


Column Name 

Data Type Length Description 

RDB$CHARACTER 

SETJD 

SMALLINT 


Identifier of the underlying character set of this collation 
sequence. Required before collation can proceed; deter¬ 
mines which character set is in use. Corresponds to the 
RDB$CHARACTER SET ID column in the 
RDB$CHARACTER_SETS table. 

RDB$COLLATION 

ATTRIBUTES 

SMALLINT 


Reserved for internal use. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the generator is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. Contains a user-written description of the 
collation sequence. 

RDB$FUNCTION_NAME 

CHAR 

31 

Reserved for internal use. 


RDB$DATABASE 


RDB$DATABASE defines a database. 


Table C-6: RDB$DATABASE 


Column Name 

Data Type Length Description 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. Contains a user-written description of the 
database. When a comment is included in a CREATE or 
ALTER SCHEMA | DATABASE statement, isql writes to 
this column. 

RDB$RELATION_ID 

SMALLINT 


For internal use by InterBase. 

RDB$SECURITY_CLASS 

CHAR 

31 

Subtype 2. Security class defined in the 
RDB$SECURITY_CLASSES table. The access control 
limits described in the named security class apply to all 
database usage. 

RDB$CHARACTER 

SET_NAME 

CHAR 

31 

Subtype 2. Name of character set. 
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RDB$DEPENDENCIES 


RDB$DEPENDENCIES keeps track of the tables and columns upon which other 
system objects depend. These objects include views, triggers, and computed col¬ 
umns. InterBase uses this table to ensure that a column or table cannot be 
deleted if it is used by any other object. 

Table C-7: RDB$DEPENDENCIES 


Column Name 

Data Type 

Length Description 

RDB$DEPENDENT 

NAME 

CHAR 

31 

Subtype 2. Names the object this table tracks: a view, 
trigger, or computed column. 

RDB$DEPENDED ON 
NAME 

CHAR 

31 

Subtype 2. Names the table referenced by the object 
named above. 

RDB$FIELD_NAME 

CHAR 

31 

Subtype 2. Names the column referenced by the object 
named above. 

RDB$DEPENDENT_TYPE SMALLINT 


Describes the object type of the object referenced In the 
RDB$DEPENDENT_NAME column. 


Type codes (RDB$TYPES): 

• 0 - table • 6 - expresslonjndex 

• 1 - view • 7 - exception 

• 2 - trigger • 8 - user 

• 3 - computed_field • 9 - field 

• 4-validation • 10-index 

• 5 - procedure 

All other values are reserved for future use. 

RDB$DEPENDED_ON_ SMALLINT Describes the object type of the object referenced in the 

TYPE RDB$DEPENDED_ON_NAME column. 

Type codes (RDB$TYPES): 

• 0 - table • 6 - expresslonjndex 

• 1 - view • 7 - exception 

• 2 - trigger • 8 - user 

• 3 - computedjield • 9 - field 

• 4-validation • 10-index 

• 5 - procedure 

All other values are reserved for future use. 
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RDB$EXCEPTIONS 


RDB$EXCEPTIONS describes error conditions related to stored procedures, 
including user-defined exceptions. 


Table C-8: RDB$EXCEPTIONS 


Column Name 

Data Type Length Description 

RDB$EXCEPTION_NAME 

CHAR 

31 

Subtype 2. Exception name. 

RDB$EXCEPTION 

NUMBER 

INTEGER 


Number for the exception. 

RDB$MESSAGE 

VARCHAR 

78 

Text of exception message. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. Text description of the exception. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the exception is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 


RDB$FIELD_DIMENSIONS 


RDB$EIELD_DIMENSIONS describes each dimension of an array column. 


Table C-9: RDB$FIELD_DIMENSIONS 


Column Name 

Data Type Length Description 

RDB$FIELD_NAME 

CHAR 

31 Subtype 2. Names the array column described by this 
table. The column name must exist In the 
RDB$FIELD_NAME column of RDB$FIELDS. 

RDB$DIMENSION 

SMALLINT 

Identifies one dimension of the ARRAY column. The first 
dimension is identified by the integer 0. 

RDB$LOWER_BOUND 

INTEGER 

Indicates the lower bound of the previously specified 
dimension. 

RDB$UPPER_BOUND 

INTEGER 

Indicates the upper bound of the previously specified 
dimension. 
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RDB$FIELDS 


RDB$FIELDS defines the characteristics of a column. Each domain or column 
has a corresponding row in RDB$EIELDS. Columns are added to tables by 
means of an entry in the RDB$RELATION_EIELDS table, which describes local 
characteristics. 

Eor domains, RDB$EIELDS includes domain name, null status, and default val¬ 
ues. SQL columns are defined in RDB$RELATION_EIELDS. Eor both domains 
and simple columns, RDB$RELATION_EIELDS may contain default and null 
status information. 

Table C-10: RDB$FIELDS 

Column Name Data Type Length Description 

RDBSFIELD NAME CHAR 31 Unique name of a domain or system-assigned name for 

a column, starling with SQLnnn. The actual column 
names are stored in the RDB$FIELD_SOURCE column 
of RDB$RELATION_FIELDS. 

RDB$QUERY_NAME CHAR 31 Not used for SQL objects. 

RDB$VALIDATION_BLR BLOB 80 Not used for SQL objects. 

RDB$VALIDATION_ BLOB 80 Not used for SQL objects. 

SOURCE 

RDBSCOMPUTED BLR BLOB 80 Subtype BLR. For computed columns, contains the BLR 

(Binary Language Representation) of the expression 
the database evaluates at the time of execution. 

RDB$COMPUTED_ BLOB 80 Subtype Text. For computed columns, contains the origi- 

SOURCE nal CHAR source expression for the column. 

RDB$DEFAULT_VALUE BLOB 80 Stores default rule. Subtype BLR. 

RDB$DEFAULT_SOURCE BLOB 80 Subtype Text. SQL description of a default value. 

RDB$FIELD_LENGTH SMALLINT Contains the length of the column defined in this row. 

Non-CHAR column lengths are: 

• D_FLOAT-8 • SHORT-2 

• DOUBLE-8 • LONG-4 

• DATE-8 • QUAD-8 

• BLOB-8 • FLOAT-4 

RDB$FIELD_SCALE SMALLINT Stores negative scale for numeric and decimal types. 
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Table C-10: RDB$FIELDS (Continued) 


Column Name Data Type Length Description 


RDB$FIELD_TYPE SMALLINT 


RDB$FIELD_SUB_TYPE SMALLINT 


Specifies the data type of the column being defined. 
Changing the value of this column automatically 
changes the data type for all columns based on the 
column being defined. Valid values are: 


SMALLINT - 7 
INTEGER - 8 
QUAD - 9 
FLOAT -10 
D_FLOAT-11 


CHAR-14 
DOUBLE - 27 
DATE - 35 
VARCHAR- 37 
BLOB - 261 


Restrictions: 

• The value of this column cannot be changed to or 
from BLOB. 

• Non-numeric data causes a conversion error in a 
column changed from CHAR to numeric. 

Changing data from CHAR to numeric and back again 
adversely affects index performance. For best results, 
delete and re-create indexes when making this type of 
change. 

Used to distinguish types of BLOBs. Predefined sub- 


types for BLOB columns are: 


• 0 - unspecified 

• 5 - encoded descrip¬ 

• 1 - text 

tion of a table's cur¬ 

• 2 - BLR (Binary Lan¬ 

rent metadata 

guage Representa¬ 

• 6 - description of 

tion) 

multi-database trans¬ 

• 3 - access control list 

action that finished 

• 4 - reserved for future 

use 

irregularly 


RDB$MISSING_VALUE BLOB 
RDB$MISSING_SOURCE BLOB 
RDB$DESCRIPTION BLOB 

RDB$SYSTEM_FLAG SMALLINT 


Predefined subtypes for CHAR columns are: 

• 0 - unspecified 

• 1 - fixed BINARY data 

Corresponds to the RDB$FIELD_SUB_TYPE column in 
the RDB$COLLATIONS table. 

80 Not used for SQL objects. 

80 Not used for SQL objects. 

80 Subtype Text. Contains a user-written description of the 
column being defined. 

For system tables. 
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Table C-10: RDB$FIELDS (Continued) 


Column Name 

Data Type Length Description 

RDB$QUERY_HEADER 

BLOB 

80 

Not used for SQL objects. 

RDB$SEGMENT 

LENGTH 

SMALLINT 


Used for BLOB columns only; a non-binding suggestion 
for the length of BLOB buffers. 

RDB$EDIT_STRING 

VARCHAR 

125 

Not used for SQL objects. 

RDB$EXTERNAL 

LENGTH 

SMALLINT 


Length of the column as it exists in an external table. If 
the column Is not In an external table, this value is 0. 

RDB$EXTERNAL_SCALE 

SMALLINT 


Scale factor for an external column of an integer data 
type. The scale factor Is the power of 10 by which the 
integer is multiplied. 

RDB$EXTERNAL_TYPE 

SMALLINT 


Indicates the data type of the column as it exists in an 
external table. Valid values are: 

• SMALLINT-7 • DOUBLE - 27 

• INTEGER-8 • DATE - 35 

• QUAD-9 • VARCHAR-37 

• FLOAT-10 • ‘C’string (null 

• D FLOAT -11 terminated text) - 40 

• CHAR-14 • BLOB-261 

RDB$DIMENSIONS 

SMALLINT 


For an ARRAY data type, specifies the number of 
dimensions in the array. For a non-array column, the 
value is 0. 

RDB$NULL_FLAG 

SMALLINT 


Indicates whether a column can contain a NULL value. 
Values: 

• Empty: Can contain NULL values. 

• 1: Cannot contain NULL values. 

RDB$CHARACTER 

LENGTH 

SMALLINT 


Length of character in bytes. 

RDB$COLLATION_ID 

SMALLINT 


Unique identifier for the collation sequence. 

RDB$CHARACTER 

SETJD 

SMALLINT 


ID indicating character set for the character or BLOB 
columns. Joins to the CHARACTER SETJD column of 
the RDB$CHARACTER_SETS system table. 
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RDB$FILES 


RDB$FILES lists the secondary files and shadow files for a database. 


Table C-11: RDB$FILES 


Column Name 

Data Type Length Description 

RDB$FILE_NAME 

VARCHAR 

253 Names either a secondary file or a shadow file for the 
database. 

RDB$FILE_SEQUENCE 

SMALLINT 

Eitherthe order that secondary files are to be used in the 
database or the order of files within a shadow set. 

RDB$FILE_START 

INTEGER 

Specifies the starting page number for a secondary file 
or shadow file. 

RDB$FILE_LENGTH 

INTEGER 

Specifies the file length in blocks. 

RDB$FILE_FLAGS 

SMALLINT 

Reserved for system use. 

RDB$SHADOW_NUMBER 

SMALLINT 

Set number of a shadow file. Set number indicates to 
which shadow set the file belongs. If the value of this col¬ 
umn is 0 or missing, InterBase assumes the file being 
defined is a secondary file, not a shadow file. 


RDB$FILTERS 


RDB$FILTERS tracks information about a BLOB filter. 
TableC-12: RDB$FILTERS 


Column Name 

Data Type Length Description 

RDB$FUNCTION_NAME 

CHAR 

31 

Unique name for the filter defined by this row. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. Contains a user-written description of the 
filter being defined. 

RDB$MODULE_NAME 

VARCHAR 

253 

Names the library where the filter executable is stored. 

RDB$ENTRYPOINT 

CHAR 

31 

The entry point within the filter library for the BLOB filter 
being defined. 

RDB$INPUT_SUB_TYPE 

SMALLINT 


The BLOB subtype of the input data. 

RDB$OUTPUT SUB 

TYPE 

SMALLINT 


The BLOB subtype of the output data. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the filter is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 
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RDB$FORMATS 

RDB$FORMATS keeps track of the formats of the columns in a table. InterBase 
assigns the table a new format number at each change to a column definition. 
This table allows existing application programs to access a changed table, with¬ 
out needing to be recompiled. 

TableC-13: RDB$FORMATS 

Column Name Data Type Length Description 

RDB$RELATION_ID SMALLINT Names a table that exists in RDB$RELATIONS. 

RDB$FORMAT SMALLINT Specifies the format number of the table. A table can 

have any number of different formats, depending on the 
number of updates to the table. 

RDB$DESCRIPTOR BLOB 80 Subtype Format. Lists each column in the table, along 

with its data type, length, and scale (if applicable). 


RDB$FUNCTION_ARGUMENTS 

RDB$FUNCTION_ARGUMENTS defines the attributes of a function argument. 


Table C-14: RDB$FUNCTION_ARGUMENTS 


Column Name 

Data Type 

Length Description 

RDB$FUNCTION 

NAME 

CHAR 

31 Unique name of the function with which the argument is 

associated. Must correspond to a function name in 
RDB$FUNCTIONS. 

RDB$ARGUMENT 

POSITION 

SMALLINT 

Position of the argument described in the 
RDB$FUNCTION_NAME column in relation to the other 
arguments. 

RDB$MECHANISM 

SMALLINT 

Specifies whether the argument is passed by value 
(value of 0) or by reference (value of 1). 

RDB$FIELD_TYPE 

SMALLINT 

Data type of the argument being defined. Valid values: 

• SMALLINT-7 • CHAR-14 

• INTEGER-8 • DOUBLE - 27 

• QUAD-9 • DATE-35 

• FLOAT-10 • VARCHAR-37 

• D_FLOAT-11 • BLOB-261 
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Table C-14: RDB$FUNCTION_ARGUI\/IENTS (Continued) 

Column Name Data Type Length Description 

RDB$FIELD_ SMALLINT Scale factor for an argument that has an Integer data 

SCALE type. The scale factor is the power of 10 by which the 

integer is multiplied. 

RDB$FIELD_ SMALLINT Contains the length of the argument defined in this row. 

LENGTFI Valid column lengths: 

• SMALLINT-2 • D_FLOAT - 8 

• INTEGER-4 • DOUBLE - 8 

• QUAD-8 • DATE-8 

• FLOAT-4 • BLOB-8 

RDB$FIELD_ SMALLINT Reserved for future use. 

SUBTYPE 

RDB$CFIARACTER SMALLINT Unique numeric identifier for a character set. 

_SETJD 

RDB$FUNCTIONS 

RDB$FUNCTIONS defines a user-defined function. 

TableC-15: RDB$FUNCTIONS 

Column Name Data Type Length Description 

RDB$FUNCTION_NAME CFIAR 31 Unique name for a function. 

RDB$FUNCTION_TYPE SMALLINT Reserved for future use. 

RDB$QUERY_NAME CFIAR 31 Alternate name for the function that can be used in isql. 

RDB$DESCRIPTION BLOB 80 Subtype Text. Contains a user-written description of the 

function being defined. 

RDB$MODULE_NAME VARCFIAR 253 Names the function library where the executable func¬ 

tion is stored. 

RDB$ENTRYPOINT CFIAR 31 Entry point within the function library for the function 

being defined. 

RDB$RETURN_ SMALLINT Position of the argument returned to the calling program. 

ARGUMENT This position is specified in relation to other arguments. 

RDB$SYSTEM_FLAG SMALLINT Indicates whether the function is: 

• User-defined (value of 0) 

• System-defined (value of 1) 
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RDB$GENERATORS 


RDB$GENERATORS stores information about generators, which provide the 
ability to generate a unique identifier for a table. 


TableC-16: RDB$GENERATORS 


Column Name 

Data Type Length Description 

RDB$GENERATOR_ 

NAME 

RDB$GENERATOR_ID 

RDB$SYSTEM_FLAG 

CHAR 31 

SMALLINT 

SMALLINT 

Name of the table to contain the unique identifier 
produced by the number generator. 

Unique system-assigned ID number for the generator. 
Indicates whether the generator is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 


RDB$INDEX_SEGMENTS 


RDB$INDEX_SEGMENTS specifies the columns that comprise an index for a 
table. Modifying these rows corrupts rather than changes an index unless the 
RDB$INDIGES row is deleted and re-created in the same transaction. 


TableC-17: RDB$INDEX_SEGMENTS 

Column Name 

Data Type Length Description 

RDB$INDEX_NAME 

CHAR 

31 

The index associated with this index segment. If the 
value of this column changes, the RDB$INDEX_NAME 
column in RDB$INDICES must also be changed. 

RDB$FIELD_NAME 

CHAR 

31 

The index segment being defined. The value of this 
column must match the value of the RDB$FIELD NAME 
column in RDB$RELATION_FIELDS. 

RDB$FIELD_POSITION 

SMALLINT 


Position of the index segment being defined. 
Corresponds to the sort order of the index. 
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RDB$INDICES 


RDB$INDICES defines the index structures that allow InterBase to locate rows 
in the database more quickly. Because InterBase provides both simple indexes (a 
single-key column) and multi-segment indexes (multiple-key columns), each 
index defined in this table must have corresponding occurrences in the 
RDB$INDEX_SEGMENTS table. 

TableC-18: RDB$INDICES 

Column Name Data Type Length Description 

RDB$INDEX_NAME CHAR 31 Names the index being defined. If the value of this 

column changes, change its value in the 
RDB$INDEX_SEGMENTS table. 

RDB$RELATION_NAME CHAR 31 Names the table associated with this index. The table 

must be defined in the RDB$RELATIONS table. 

RDB$INDEX_ID SMALLINT Contains an internal Identifier for the index being 

defined. Do nof write to this column. 

RDB$UNIQUE_FLAG SMALLINT Specifies whether the index allows duplicate values. 

Values: 

• 0 - allows duplicate values 

• 1 - does not allow duplicate values 
Eliminate duplicates before creating a unique index. 

RDB$DESCRIPTION BLOB 80 Subtype Text. User-written description of the index. 

When including a comment in a CREATE INDEX or 
ALTER INDEX statement, isql writes to this column. 

RDB$SEGMENT_COUNT SMALLINT Number of segments in the index. A value of 1 indicates 

a simple index. 

RDB$INDEXJNACTIVE SMALLINT Indicates whether the index is: 

• Active (value of 0) 

• Inactive (value of 2) 

RDB$INDEX_TYPE SMALLINT Reserved for future use. 

RDB$FOREIGN_KEY CHAR 31 Name of FOREIGN KEY constraint for which the index 

is implemented. 

RDB$SYSTEM_FLAG SMALLINT Indicates whether the Index Is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 

RDB$EXPRESSION_BLR BLOB 80 Subtype BLR. Contains the BLR (Binary Language Rep¬ 

resentation) for the expression, evaluated by the data¬ 
base at execution time. Used for PC semantics. 
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Table C-18: RDB$INDICES (Continued) 


Column Name 

Data Type Length Description 

RDB$EXPRESSION 

SOURCE 

BLOB 

80 Subtype Text. Contains original text source for the col¬ 
umn. Used for PC semantics. 

RDB$STATISTICS 

DOUBLE 

PRECI¬ 

SION 

Selectivity factor for the index. Index selectivity, a 
measure of uniqueness for indexed columns, is used by 
the optimizer to choose an access strategy for a query. 


RDB$LOG_FILES 


RDB$LOG_FILES stores WAL protocol file information for a database. 


Table C-19: RDB$LOG_FILES 


Column Name 

Data Type Length Description 

RDB$FILE_NAME 

VARCHAR 

253 Name of the current log file. 

RDB$FILE_SEOUENCE 

SMALLINT 

Log file sequence file number. 

RDB$FILE_LENGTH 

INTEGER 

Log file size in kilobytes. 

RDB$FILE_PARTITIONS 

SMALLINT 

Number of log file partitions. 

RDB$FILE_P_OFFSET 

INTEGER 


RDB$FILE_FLAGS 

SMALLINT 

Flags for RBD$LOG_FILES: 

• 1 - LOG_serlal. Any serial log file. Including default 
log configuration and overflow files. 

• 2 - LOG_default. If log file name Is not specified, 
the default is database-name.log.n. 

• 4 - LOG_raw. On raw device. 

• 8 - LOG_overflow. Overflow files. 


RDB$PAGES 


RDB$PAGES keeps track of each page allocated to the database. Modifying this 
table in any way corrupts a database. 

Table C-20: RDB$PAGES 

Column Name Data Type Length Description 

RDB$PAGE_NUMBER INTEGER The physically allocated page number. 

RDB$RELATION_ID SMALLINT Identifier number of the table for which this page is 

allocated. 
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Table C-20: RDB$PAGES (Continued) 


Column Name Data Type Length Description 

RDB$PAGE_SEQUENCE INTEGER The sequence number of this page in the table to other 

pages allocated for the previously identified table. 
RDB$PAGE_TYPE SMALLINT Describes the type of page. This information is for 

system use only. 


RDB$PROCEDURE_PARAMETERS 


RDB$PROCEDURE_PARAMETERS stores information about each parameter 
for each of a database's procedures. 


Table C-21: RDB$PROCEDURE_PARAMETERS 


Column Name 

Data Type Length Description 

RDB$PARAMETER 

NAME 

CHAR 

31 

Parameter name. 

RDB$PROCEDURE 

NAME 

CHAR 

31 

Name of the procedure in which the parameter is used. 

RDB$PARAMETER 

NUMBER 

SMALLINT 


Parameter sequence number. 

RDB$PARAMETER_TYPE 

SMALLINT 


Parameter data type. Values: 

• 0 = input 

• 1 = output 

RDB$FIELD_SOURCE 

CHAR 

31 

Global column name. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. User-written description of the parameter. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the parameter is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 


RDB$PROCEDURES 

RDB$PROCEDURES stores information about a database's stored procedures. 
Table C-22: RDB$PROCEDURES 

Column Name Data Type Length Description 

RDB$PROCEDURE_ CHAR 31 Procedure name. 

NAME 
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Table C-22: RDB$PROCEDURES (Continued) 


Column Name 

Data Type Length Description 

RDB$PROCEDUREJD 

SMALLINT 


Procedure number. 

RDB$PROCEDURE 

INPUTS 

SMALLINT 


Number of input parameters. 

PROCEDURE 

OUTPUTS 

SMALLINT 


Number of output parameters. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. User-written description of the procedure. 

RDB$PROCEDURE 

SOURCE 

BLOB 

80 

Subtype Text. Source code for the procedure. 

RDB$PROCEDURE_BLR 

BLOB 

80 

Subtype BLR. BLR (Binary Language Representation) of 
the procedure source. 

RDB$SECURITY_CLASS 

CHAR 

31 

Security class of the procedure. 

RDB$OWNER_NAME 

CHAR 

31 

User who created the procedure. (Owner for SOL 
security purposes.) 

RDB$RUNTIME 

BLOB 

80 

Subtype Summary. Describes procedure metadata. 

Used for performance enhancement. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the procedure is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 


RDB$REF_CONSTRAINTS 


RDB$REF_CONSTRAINTS stores referential integrity constraint information. 
Table C-23: RDB$REF_CONSTRAINTS 


Column Name 

Data Type Length Description 

RDB$CONSTRAINT 

NAME 

CHAR 

31 

Name of a referential constraint. 

RDB$CONST_NAME_UQ 

CHAR 

31 

Name of a referenced PRIMARY KEY or UNIQUE 
constraint. 

RDB$MATCH_OPTION 

CHAR 

7 

Reserved for later use. Currently defaults to FULL. 

RDB$UPDATE_RULE 

CHAR 

11 

Reserved for later use. Currently defaults to RESTRICT. 

RDB$DELETE_RULE 

CHAR 

11 

Reserved for later use. Currently defaults to RESTRICT. 
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RDB$RELATION_CONSTRAINTS 

RDB$RELATION_CONSTRAINTS stores information about integrity con¬ 
straints for tables. 


Table C-24: RDB$RELATION_CONSTRAINTS 


Column Name 

Data Type Length Description 

RDB$CONSTRAINT 

NAME 

CHAR 

31 

Name of a table constraint. 

RDB$CONSTRAINT 

TYPE 

CHAR 

11 

Type of table constraint. Types: 

• PRIMARY KEY 

• UNIQUE 

• FOREIGN KEY 

• CHECK 

• NOT NULL 

RDB$RELATION_NAME 

CHAR 

31 

Name of the table for which the constraint is defined. 

RDB$DEFERRABLE 

CHAR 

3 

Reserved for later use. Currently defaults to No. 

RDB$INITIALLY 

DEFERRED 

CHAR 

3 

Reserved for later use. Currently defaults to No. 

RDB$INDEX_NAME 

CHAR 

31 

Name of the index used by UNIQUE, PRIMARY KEY, or 
FOREIGN KEY constraints. 


RDB$RELATION_FIELDS 

For database tables, RDB$RELATION_FIELDS lists columns and describes col¬ 
umn characteristics for domains. 

SQL columns are defined in RDB$RELATION_FIELDS. The column name is cor¬ 
related in the RDB$FIELD_SOURCE column to an underlying entry in 
RDB$FIELDS that contains a system name ("SQL$<n>"). This entry includes 
information about column t5^e, length, etc. For both domains and simple col¬ 
umns, this table may contain default and nullability information. 

Table C-25: RDB$RELATION_FIELDS 

Column Name Data Type Length Description 

RDB$FIELD_NAME CHAR 31 Name of the column whose characteristics being 

defined. The combination of the values in this column 
and in the RDB$RELATION_NAME column In this table 
must be unique. 
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Table C-25: RDB$RELATION_FIELDS (Continued) 


Column Name 

RDB$RELATION_NAME 

RDB$FIELD_SOURCE 

RDB$QUERY_NAME 

RDB$BASE_FIELD 

RDB$EDIT_STRING 

RDB$FIELD_POSITION 


RDB$QUERY_HEADER 

RDB$UPDATE_FLAG 

RDB$FIELDJD 

RDB$VIEW_CONTEXT 

RDB$DESCRIPTION 


Data Type Length Description 


CHAR 

CHAR 

CHAR 

CHAR 


VARCHAR 

SMALLINT 


31 Table to which a particular column belongs. A table with 
this name must appear in RDB$RELATIONS. The com¬ 
bination of the values in this column and in the 
RDB$FIELD column in this table must be unique. 

31 The name for this column in the RDB$FIELDS table. If 
the column is based on a domain, contains the domain 
name. 

31 Alternate column name for use in isql; supersedes the 
value in RDB$FIELDS. 

31 Views only: The name of the column from RDB$FIELDS 
in a table or view that is the base for a view column 
being defined. For the base column: 

• RDB$BASE_FIELD provides the column name. 

• RDB$VIEW_CONTEXT, a column in this table, 
provides the source table name. 

125 Not used in SQL. 

The position of the column in relation to other columns: 

• isql obtains the ordinal position for displaying col¬ 
umn values when printing rows from this column. 

• gpre uses the column order for SELECT and 
INSERT statements. 

If two or more columns in the same table have the same 
value for this column, those columns appear in random 
order. 


BLOB 

SMALLINT 

SMALLINT 


SMALLINT 


BLOB 


Not used in SQL. 

Not used by InterBase. Included for compatibility with 
other DSRI-based systems. 

Identifier for use in BLR (Binary Language Representa¬ 
tion) to name the column. Because this identifier 
changes during backup and restoration of the database, 
try to use it in transient requests only. Do not modify this 
column. 

Alias used to qualify view columns by specifying the 
table location of the base column. It must have the same 
value as the alias used in the view BLR (Binary Lan¬ 
guage Representation) for this context stream. 

Subtype Text. User-written description of the column 
being defined. 
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Table C-25: RDB$RELATION_FIELDS (Continued) 


Column Name 

Data Type Length Description 

RDB$DEFAULT_VALUE 

BLOB 

80 

Subtype BLR. BLR (Binary Language Representation) 
for default clause. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the column is: 




• User-defined (value of 0) 

• System-defined (value greater than 0) 

RDB$SECURITY_CLASS 

CHAR 

31 

Names a security class defined in the 
RDB$SECURITY_CLASSES table. The access restric¬ 
tions defined by this security class apply to all users of 
this column. 

RDB$COMPLEX_NAME 

CHAR 

31 

Reserved for future use. 

RDB$NULL_FLAG 

SMALLINT 


Indicates whether the column may contain NULLs. 

RDB$DEFAULT 

SOURCE 

BLOB 

80 

Subtype Text. SQL source to define defaults. 

RDB$COLLATIONJD 

SMALLINT 


Unique identifier for the collation sequence. 



RDB$RELATIONS 


RDB$RELATIONS defines some of the characteristics of tables and views. Other 
characteristics, such as the columns included in the table and a description of 
each column, are stored in the RDB$RELATION_FIELDS table. 


Table C-26: RDB$RELATIONS 


Column Name 

Data Type Length Description 

RDB$VIEW_BLR 

BLOB 

80 

Subtype BLR. For a view, contains the BLR (Binary Lan¬ 
guage Representation) of the query InterBase evalu¬ 
ates at the time of execution. 

RDB$VIEW_SOURCE 

BLOB 

80 

Subtype Text. For a view, contains the original source 
query for the view definition. 

RDB$_DESCRIPTION 

BLOB 

80 

Subtype Text. Contains a user-written description of the 
table being defined. 

RDB$RELATION_ID 

SMALLINT 


Contains the internal identification number used in BLR 
(Binary Language Representation) requests. Do not 
modify this column. 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates the contents of a table, either: 

• User-data (value of 0). 

• System information (value greater than 0) 

Do not set this column to 1 when creating tables. 
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Table C-26: RDB$RELATIONS (Continued) 


Column Name 

Data Type Length Description 

RDB$DBKEY_LENGTH 

SMALLINT 


Length of the database key. Values: 

• For tables: 8 

• For views: 8 times the number of tables referenced 
in the view definition 

Do not modify the value of this column. 

RDB$FORMAT 

SMALLINT 


For InterBase internal use only. Do nof modify. 

RDB$FIELDJD 

SMALLINT 


The number of columns in the table. This column is 
maintained by InterBase. Do nof modify the value of this 
column. 

RDB$RELATION_NAME 

CHAR 

31 

The unique name of the table defined by this row. 

RDB$SECURITY_CLASS 

CHAR 

31 

Security class defined in the 
RDB$SECURITY_CLASSES table. Access controls 
defined in the security class apply to all uses of this 
table. 

RDB$EXTERNAL_FILE 

VARCHAR 

253 

The file in which the external table is stored. An external 
file can be either an Apollo AEGIS stream file or a VAX 
RMS file. If blank, the table does not correspond to an 
external file. 

RDB$RUNTIME 

BLOB 

80 

Subtype Summary. Describes table metadata. Used for 
performance enhancement. 

RDB$EXTERNAL 

DESCRIPTION 

BLOB 

80 

Subtype EXTERNAL_FILE_DESCRIPTION. User- 
written description of the external file. 

RDB$OWNER_NAME 

CHAR 

31 

Identifies the creator of the table or view. The creator is 
considered the owner for SQL security (GRANT/ 
REVOKE) purposes. 

RDB$DEFAULT_CLASS 

RDB$FLAGS 

CHAR 

SMALLINT 

31 

Default security class that InterBase applies to columns 
newly added to a table using the SQL security system. 
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RDB$SECURITY_CLASSES 

RDB$SECURITY_CLASSES defines access control lists and associates them with 
databases, tables, views, and columns in tables and views. Eor all SQL objects, 
the information in this table is duplicated in the RDB$USER_PRIVILEGES sys¬ 
tem table. 


Table C-27: RDB$SECURITY_CLASSES 


Column Name 

Data Type Length Description 

RDB$SECURITY_CLASS 

CHAR 

31 

Security class being defined. If the value of this column 
changes, change its name in the 

RDB$SECURITY CLASS column in 

RDB$ DATABASE, RDB$RELATIONS, and 
RDB$RELATION_FIELDS. 

RDB$ACL 

BLOB 

80 

Subtype ACL. Access control list that specifies users 
and the privileges granted to those users. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. User-written description of the security 
class being defined. 


RDB$TRANSACTIONS 


RDB$TRANSACTIONS keeps track of all multi-database transactions. 


Table C-28: RDB$TRANSACTIONS 


Column Name 

Data Type Length Description 

RDB$TRANSACTION_l D 

INTEGER 

Identifies the multi-database transaction being 
described. 

RDB$TRANSACTION 

STATE 

SMALLINT 

Indicates the state of the transaction. Valid values are: 

• 0 - limbo 

• 1 - committed 

• 2 - rolled back 

RDB$TIMESTAMP 

DATE 

Reserved for future use. 

RDB$TRANSACTION 

DESCRIPTION 

BLOB 

80 Subtype TRANSACTION_DESCRIPTION. Describes a 
prepared multi-database transaction. This description is 
available if the reconnect fails. 
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RDB$TRIGGER_MESSAGES 


RDB$TRIGGER_MESSAGES defines a trigger message and associates the mes¬ 
sage with a particular trigger. 

Table C-29: RDB$TRIGGER_MESSAGES 


Column Name 

Data Type 

Length Description 

RDB$TRIGGER_NAME 

CHAR 

31 

Names the trigger associated with this trigger message. 
The trigger name must exist in RDB$TRIGGERS. 

RDB$MESSAGE_ 

NUMBER 

SMALLINT 


The message number of the trigger message being 
defined. The maximum number of messages is 32,767. 

RDB$MESSAGE 

VARCHAR 

78 

The source for the trigger message. 


RDB$TRIGGERS 

RDB$TRIGGERS defines triggers. 

Table C-30: RDB$TRIGGERS 

Column Name Data Type Length Description 

RDB$TRIGGER_NAME CHAR 31 Names the trigger being defined. 

RDB$RELATION_NAME CHAR 31 Name of the table associated with the trigger being 

defined. This name must exist in RDB$RELATIONS. 

RDB$TRIGGER_ SMALLINT Sequence number for the trigger being defined. 

SEQUENCE Determines when a trigger is executed in relation to 

others of the same type. Triggers with the same 
sequence number execute in random order. If this num¬ 
ber is not assigned by the user, InterBase assigns a 
value of 0. 

RDB$TRIGGER_TYPE SMALLINT The type of trigger being defined. Values: 

• 1 - BEFORE INSERT 

• 2 - AFTER INSERT 

• 3 - BEFORE UPDATE 

• 4 - AFTER UPDATE 

• 5 - BEFORE DELETE 

• 6 - AFTER DELETE 

RDB$TRIGGER_SOURCE BLOB 80 Subtype Text. Original source of the trigger definition. 

The isql SHOW TRIGGERS statement displays infor¬ 
mation from this column. 
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Table C-30: RDB$TRIGGERS (Continued) 


Column Name 

Data Type 

Length Description 

RDB$TRIGGER_BLR 

BLOB 

80 

Subtype BLR. BLR (Binary Language Representation) 
of the trigger source. 

RDB$DESCRIPTION 

BLOB 

80 

Subtype Text. User-written description of the trigger 
being defined. When including a comment in a CREATE 
TRIGGER or ALTER TRIGGER statement, isql writes to 
this column. 

RDB$TRIGGER 

SMALLINT 


Indicates whether the trigger being defined is: 

INACTIVE 



• Active (value of 0) 

• Inactive (value of 1) 

RDB$SYSTEM_FLAG 

SMALLINT 


Indicates whether the trigger is: 




• User-defined (value of 0) 

• System-defined (value greater than 0) 

RDB$FLAGS 

SMALLINT 




RDB$TYPES 

RDB$TYPES records enumerated data t5^es and alias names for InterBase char¬ 
acter sets and collation orders. This capability is not available in the current 
release. 

Table C-31: RDB$TYPES 

Column Name Data Type Length Description 

RDBSFIELD NAME CHAR 31 Column for which the enumerated data type is being 

defined. 

RDB$TYPE SMALLINT Identifies the internal number that represents the column 

specified above. Type codes (same as 
RDB$DEPENDENT_TYPES): 

• 0 - table 

• 1 - view 

• 2-trigger 

• 3 - computed_field 

• 4 - validation 

• 5 - procedure 

All other values are reserved for future use. 

RDB$TYPE_NAME CHAR 31 Text that corresponds to the internal number. 

RDB$DESCRIPTION BLOB 80 Subtype Text. Contains a user-written description of the 

enumerated data type being defined. 
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Table C-31: RDB$TYPES (Continued) 

Column Name Data Type Length Description 

RDB$SYSTEM_FLAG SMALLINT Indicates whether the data type is: 

• User-defined (value of 0) 

• System-defined (value greater than 0) 

RDB$USER_PRIVILEGES 

RDB$USER_PRIVILEGES keeps track of the privileges assigned to a user 
through an SQL GRANT statement. There is one occurrence of this table for each 
user/privilege intersection. 

Table C-32: RDB$USER_PRIVILEGES 

Column Name Data Type Length Description 

CHAR 31 Names the user who was granted the privilege listed in 

the following column, RDB$PRIVILEGE. 

CHAR 31 Names the user who granted the privilege. 

CHAR 6 Identifies the privilege granted to the user listed in the 

RDB$USER column, above. Valid values are: 

• ALL 

• SELECT 

• DELETE 

• INSERT 

• UPDATE 

RDB$GRANT_OPTION SMALLINT Indicates whether the privilege was granted with the 

WITH GRANT OPTION (value of 1) or not (value of 0). 
This option enables a user to grant the same authority to 
other users. 

CHAR 31 Identifies the table to which the privilege applies. 

CHAR 31 For update privileges, identifies the column to which the 

privilege applies. 

SMALLINT 
SMALLINT 


RDB$RELATION_NAME 

RDB$FIELD_NAME 

RDB$USER_TYPE 

RDB$OBJECT_TYPE 


RDB$USER 

RDB$GRANTOR 

RDB$PRIVILEGE 
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RDB$VIEW_RELATIONS 

RDB$VIEW_RELATIONS is not used by SQL objects. 
Table C-33: RDB$VIEW_RELATIONS 


Column Name Data Type Length Description 


RDB$VIEW_NAME 

CHAR 

31 

Name of a view. The combination of RDB$VIEW NAME 
and RDB$ViEW_CONTEXT must be unique. 

RDB$RELATION_NAME 

CHAR 

31 

Name of a tabie referenced in the view definition. 

RDB$VIEW_CONTEXT 

SMALLINT 


Alias used to quaiify view columns. Must have the same 
value as the alias used in the view BLR (Binary Lan¬ 
guage Representation) for this query. 

RDB$CONTEXT_NAME 

CHAR 

31 

Textual version of the alias identified in 
RDB$VIEW_CONTEXT. This variable must: 




• Match the value of the RDB$VIEW_SOURCE col¬ 
umn for the corresponding table in 
RDB$RELATIONS. 




• Be unique in the view. 


System Views 

The four views in this section provide information about existing integrity 
constraints for a database. They must be created after a database is created. SQL 
system views are a subset of system views defined in the SQL-92 standard. Since 
they are not defined by InterBase, the names of the system view and their col¬ 
umns do not start with RDB$. 

• CHECK_CQNSTRAINTS 

• CQNSTRAINTS_CQLUMN_USAGE 

• RELERENTIAL_CQNSTRAINTS 

• TABLE_CQNSTRAINTS 
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CHECK.CONSTRAINTS 

CHECK_CONSTRAINTS identifies all CHECK constraints defined in the 
database. 


Table C-34: CHECK_CONSTRAINTS 


Column Name 

Data Type Length Description 

CONSTRAINT_NAME 

CHECK_CLAUSE 

CHAR 

BLOB 

31 

80 

Unique name for the CHECK constraint. Nullable. 
Subtype Text. Nullable. Original source of the trigger 
definition, stored in the RDB$TRIGGER SOURCE 
COLUMN in RDB$TRIGGERS. 



CONSTRAINTS_COLUMN_USAGE 


CONSTRAINTS_COLUMN_USAGE identifies columns used by PRIMARY 
KEY and UNIQUE constraints. Eor EOREIGN KEY constraints, this view identi¬ 
fies the columns defining the constraint. 


Table C-35: CONSTRAINTS_COLUMN_USAGE 


Column Name 

Data Type Length Description 

TABLE_NAME 

CHAR 

31 

Table for which the constraint is defined. Nullable. 

COLUMN_NAME 

CHAR 

31 

Column used in the constraint definition. Nullable. 

CONSTRAINT_NAME 

CHAR 

31 

Unique name for the constraint. Nullable. 


REFERENTIAL.CONSTRAINTS 


REEERENTIAL_GONSTRAINTS identifies all referential constraints defined in 
a database. 


Table C-36: REFERENTIAL_CONSTRAINTS 


Column Name 

Data Type Length Description 

CONSTRAINT_NAME 

CHAR 

31 

Unique name for the constraint. Nullable. 

UNIQUE CONSTRAINT 
NAME 

CHAR 

31 

Name of the UNIQUE or PRIMARY KEY constraint 
corresponding to the specified referenced column list. 
Nullable. 

MATCH_OPTION 

CHAR 

7 

Reserved for future use. Always set to FULL. Nullable. 
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Table C-36: REFERENTIAL_CONSTRAINTS (Continued) 

Column Name Data Type Length Description 

UPDATE_RULE CHAR 11 Reserved for future use. Always set to RESTRICT. 

Nullable. 

DELETE RULE CHAR 11 Reserved for future use. Always set to RESTRICT. 

Nullable. 


TABLE.CONSTRAINTS 


TABLE_CONSTRAINTS identifies all constraints defined in a database. 
Table C-37: TABLE_CONSTRAINTS 


Column Name 

Data Type Length Description 

CONSTRAINT_NAME 

CHAR 

31 

Unique name for the constraint. Nullable. 

TABLE_NAME 

CHAR 

31 

Table for which the constraint is defined. Nullable. 

CONSTRAINT_TYPE 

CHAR 

11 

Possible values are UNIQUE, PRIMARY KEY, 

FOREIGN KEY, and CHECK. Nullable. 

IS_DEFERRABLE 

CHAR 

3 

Reserved for future use. Always set to No. Nullable. 

INITIALLY_DEFERRED 

CHAR 

3 

Reserved for future use. Always set to No. Nullable. 
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Appendix D 

Character Sets and Collation 

Orders 


CHAR, VARCHAR, and text BLOB columns in InterBase can use many different 
character sets. A character set defines the symbols that can be entered as text in a 
column, and its also defines the maximum number of bytes of storage necessary 
to represent each symbol. In some character sets, such as IS08859_1, each sym¬ 
bol requires only a single byte of storage. In others, such as UNICODE_FSS, each 
symbol requires from 1 to 3 bytes of storage. 

Each character set also has an implicit collation order that specifies how its sym¬ 
bols are sorted and ordered. Some character sets also support alternative colla¬ 
tion orders. In all cases, choice of character set limits choice of collation orders. 

This appendix lists available character sets and their corresponding collation 
orders. 

This appendix also describes how to specify: 

• Default character set for an entire database. 

• Alternative character set for a particular column in a table. 

• Client application character set that the server should use when translat¬ 
ing data between itself and the client. 

• Collation order for a column. 

• Collation order for a value in a comparison operation. 

• Collation order in an ORDER BY clause. 

• Collation order in a GROUP BY clause. 
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InterBase Character Sets and Collation Orders 


The following table lists each character set that can be used in InterBase. For 
each character set, the minimum and maximum number of bytes used to store 
each symbol is listed, and all collation orders supported for that character set are 
also listed. The first collation order for a given character set is that set's implicit 
collation, the one that is used if no COLLATE clause specifies an alternative 
order. The implicit collation order cannot be specified in the COLLATE clause. 


Table D-1: Character Sets and Collation Orders 

Character Set 

Char. Set ID 

Max. Char. Size 

Min. Char. Size 

Collation Orders 

ASCII 

2 

1 byte 

1 byte 

ASCII 

CYRL 

50 

1 byte 

1 byte 

CYRL 

DB RUS 

PDOX_CYRL 

DOS437 

10 

1 byte 

1 byte 

DOS437 


DB_DEU437 

DB_ESP437 

DB_FIN437 

DB_FRA437 

DBJTA437 

DB_NLD437 

DB_SVE437 

DB_UK437 

DB_US437 

PDOX_ASCII 

PDOX_INTL 

PDOX_SWEDFIN 

DOS850 11 1 byte 1 byte DOS850 

DB_DEU850 

DB_ESP850 

DB_FRA850 

DB_FRC850 

DBJTA850 

DB_NLD850 

DB_PTB850 

DB_SVE850 

DB_UK850 

DB_US850 
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Table D-1: Character Sets and Collation Orders (Continued) 

Character Set 

Char. Set ID 

Max. Char. Size 

Min. Char. Size 

Collation Orders 

DOS852 

45 

1 byte 

1 byte 

DOS852 

DB CSY 

DB PLK 

DB SLO 

PDOX CSY 

PDOX HUN 

PDOX PLK 

PDOX_SLO 

DOS857 

46 

1 byte 

1 byte 

DOS857 

DB_TRK 

DOS860 

13 

1 byte 

1 byte 

DOS860 

DB_PTG860 

DOS861 

47 

1 byte 

1 byte 

DOS861 

PDOX_ISL 

DOS863 

14 

1 byte 

1 byte 

DOS863 

DB_FRC863 

DOS865 

12 

1 byte 

1 byte 

DOS865 

DB DAN865 

DB NOR865 
PDOX_NORDAN4 

EUCJ_0208 

6 

2 bytes 

1 byte 

EUJC_0208 

IS08859_1 

21 

1 byte 

1 byte 

IS08859_1 


DA_DA 

DE_DE 

DU_NL 

EN_UK 

EN_US 

ES_ES 

FLFI 

FR_CA 

FR_FR 

IS_IS 

ITJT 

NO_NO 

PT_PT 

SV_SV 

NEXT 56 1 byte 1 byte NEXT 

NXT_DEU 

NXT_FRA 

NXT_ITA 

NXT_US 
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Table D-1: Character Sets and Collation Orders (Continued) 


Character Set 

Char. Set ID 

Max. Char. Size 

Min. Char. Size 

Collation Orders 

NONE 

0 

1 byte 

1 byte 

NONE 

OCTETS 

1 

1 byte 

1 byte 

OCTETS 

SJIS_0208 

5 

2 bytes 

1 byte 

SJIS_0208 

UNICODE_FSS 

3 

3 bytes 

1 byte 

UNICODE_FSS 

WIN 1250 

51 

1 byte 

1 byte 

WIN1250 

PXW CSY 

PXW HUNDC 

PXW PLK 

PXW_SLO 

WIN1251 

52 

1 byte 

1 byte 

WIN1251 

PXW_CYRL 

WIN1252 

53 

1 byte 

1 byte 

WIN1252 

PXW INTL 

PXW INTL850 

PXW NORDAN4 

PXW SPAN 
PXW_SWEDFIN 

WIN1253 

54 

1 byte 

1 byte 

WIN1253 

PXW_GREEK 

WIN1254 

55 

1 byte 

1 byte 

WIN1254 

PXW_TURK 


Character Set Storage Requirements 

Knowing the storage requirements of a particular character set is important, 
because in the case of CHAR columns, InterBase restricts the maximum amount 
of storage in each field in the column to 32,767 bytes (VARCHAR is restricted to 
32,765 bytes). 

For character sets that require only a single byte of storage, the maximum num¬ 
ber of symbols that can be stored in a single field corresponds to the number of 
bytes. For character sets that require up to three bytes per symbol, the maximum 
number of symbols that can be safely stored in a field is 1/3 of the maximum 
number of bytes for the data t 5 q)e. For example, for a CHAR column defines to 
use the UNICODE_FSS character set, the maximum number of characters that 
can be specified is 10,922 (32,767/3): 

CHAR(10922) CHARACTER SET UNICODE_FSS, 


220 


Language Reference 



Paradox and dBASE Character Sets and Collations 

Many character sets and their corresponding collations are provided to support 
Borland Paradox for DOS, Paradox for Windows, dBASE for DOS, and dBASE 
for Windows. 


Character Sets for DOS 

The following character sets correspond to MS-DOS code pages, and should be 
used to specify character sets for InterBase databases that are accessed by 
Paradox for DOS and dBASE for DOS: 

Table D-2: Character Sets Corresponding to DOS Code Pages 

Character Set 

DOS Code Page 

DOS437 

437 

DOS850 

850 

DOS852 

852 

DOS857 

857 

DOS860 

860 

DOS861 

861 

DOS863 

863 

DOS865 

865 


The names of collation orders for these character sets that are specific to Paradox 
begin "PDOX". Por example, the DOS865 character set for DOS code page 865 
supports a Paradox collation order for Norwegian and Danish called 
"PDOX_NORDAN4". 

The names of collation orders for these character sets that are specific to dBASE 
begin "DB". Eor example, the DOS437 character set for DOS code page 437 sup¬ 
ports a dBASE collation order for Spanish called "DB_ESP437". 

Eor more information about DOS code pages, and Paradox and dBASE collation 
orders, see the appropriate Paradox and dBASE documentation and driver 
books. 


Character Sets for Microsoft Windows 

There are five character sets that support Windows client applications, such as 
Paradox for Windows. These character sets are WIN1250, WIN1251, WIN1252, 
WIN1253, and WIN1254. 
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The names of collation orders for these character sets that are specific to Paradox 
for Windows begin "PXW". For example, the WIN125 character set supports a 
Paradox for Windows collation order for Norwegian and Danish called 
"PXW_NORDAN4". 

For more information about Windows character sets and Paradox for Windows 
collation orders, see the appropriate Paradox for Windows documentation and 
driver books. 


Additional Character Sets and Collations 

Support for additional character sets and collation orders is constantly being 
added to InterBase. To see if additional character sets and collations are available 
for a newly created database, connect to the database with isql, then use the fol¬ 
lowing set of queries to generate a list of available character sets and collations: 

SELECT RDB$CHARACTER_SET_NAME, RDB$CHARACTER_SET_ID 
FROM RDB$CHARACTER_SETS 
ORDER BY RDB$CHARACTER_SET_NAME; 

SELECT RDB$COLLATION_NAME, RDB$CHARACTER_SET_ID 
FROM RDB$COLLATIONS 
ORDER BY RDB$COLLATION_NAME; 


Specifying a Defauit Character Set for a Database 

A database's default character set designation specifies the character set the 
server uses to tag CHAR, VARCHAR, and text BLOB columns in the database 
when no other character set information is provided. When data is stored in 
such columns without additional character set information, the server uses the 
tag to determine how to store and transliterate that data. A default character set 
should always be specified for a database when it is created with CREATE 
DATABASE. 

To specify a default character set, use the DEEAULT CHARACTER SET clause of 
CREATE DATABASE. Eor example, the following statement creates a database 
that uses the IS08859_1 character set: 

CREATE DATABASE "europe.gdb" DEFAULT CHARACTER SET IS08859_1; 

Important If you do not specify a character set, the character set defaults to NONE. 

Using character set NONE means that there is no character set assumption 
for columns; data is stored and retrieved just as you originally entered it. 

You can load any character set into a column defined with NONE, but you 
carmot later move that data into another column that has been defined 
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with a different character set. In this case, no transliteration is performed 
between the source and destination character sets, and errors may occur 
during assignment. 

For the complete S 5 mtax of CREATE DATABASE, see "CREATE DATABASE" in 
Chapter 2: "SQL Statement and Eunction Reference." 


Specifying a Character Set for a Coiumn in a Tabie 

Character sets for individual columns in a table can be specified as part of the 
column's CHAR or VARCHAR data t 5 ^e definition. When a character set is 
defined at the column level, it overrides the default character set declared for the 
database. Eor example, the following isql statements create a database with a 
default character set of IS08859_1, then create a table where two column defini¬ 
tions include a different character set specification: 

CREATE DATABASE "europe.gdb" DEFAULT CHARACTER SET IS08859_1; 

CREATE TABLE RUS_NAME( 

LNAME VARCHAR(30) NOT NULL CHARACTER SET CYRL, 

FNAME VARCHAR(20) NOT NULL CHARACTER SET CYRL, 

Eor the complete syntax of CREATE TABLE, see "CREATE TABLE" in Chapter 
2: "SQL Statement and Eunction Reference." 


Specifying a Character Set for a Ciient Attachment 

When a client application, such as isql, cormects to a database, it may have its 
own character set requirements. The server providing database access to the cli¬ 
ent does not know about these requirements unless the client specifies them. The 
client application specifies its character set requirement using the SET NAMES 
statement before it connects to the database. 

SET NAMES specifies the character set the server should use when translating 
data from the database to the client application. Similarly, when the client sends 
data to the database, the server translates the data from the client's character set 
to the database's default character set (or the character set for an individual col¬ 
umn if it differs from the database's default character set). 

Eor example, the following isql command specifies that isql is using the DQS437 
character set. The next command connects to the europe database created above, 
in "Specifying a Character Set for a Column in a Table": 
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SET NAMES DOS437; 

CONNECT "europe.gdb" USER "JAMES" PASSWORD "U4EEAH"; 

For the complete S 5 mtax of SET NAMES, see "SET NAMES" in Chapter 2: "SQL 
Statement and Eunction Reference." Eor the complete S 5 mtax of CONNECT, see 
"CONNECT" in Chapter 2: "SQL Statement and Eunction Reference." 


Specifying Coiiation Order for a Coiumn 

When a CHAR or VARCHAR column is created for a table, either with CREATE 
TABLE or ALTER TABLE, the collation order for the column can be specified 
using the COLLATE clause. COLLATE is especially useful for character sets 
such as IS08859_1 or DOS437 that support many different collation orders. 

Eor example, the following isql ALTER TABLE statement adds a new column to 
a table, and specifies both a character set and a collation order: 

ALTER TABLE "FR_CA_EMP" 

ADD ADDRESS VARCHAR(40) CHARACTER SET IS08859_1 NOT NULL 
COLLATE FR_CA; 

Eor the complete syntax of ALTER TABLE, see "ALTER TABLE" in Chapter 2: 
"SQL Statement and Eunction Reference." 


Specifying Coiiation Order in a Comparison Operation 

When CHAR or VARCHAR values are compared in a WHERE clause, it can be 
necessary to specify a collation order for the comparisons if the values being 
compared use different collation orders. 

To specify the collation order to use for a value during a comparison, include a 
COLLATE clause after the value. Eor example, in the following WHERE clause 
fragment from an embedded application, the value to the left of the comparison 
operator is forced to be compared using a specific collation: 

WHERE LNAME COLLATE FR_CA = :lname_search; 

Eor the complete syntax of the WHERE clause, see "SELECT" in Chapter 2: 
"SQL Statement and Eunction Reference." 
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Specifying Coiiation Order in an ORDER BY Ciause 


When CHAR or VARCHAR columns are ordered in a SELECT statement, it can 
be necessary to specify a collation order for the ordering, especially if columns 
used for ordering use different collation orders. 

To specify the collation order to use for ordering a column in the ORDER BY 
clause, include a COLLATE clause after the column name. Eor example, in the 
following ORDER BY clause, the collation order for two columns is specified: 


ORDER BY LNAME COLLATE FR_CA, FNAME COLLATE FR_CA; 

Eor the complete syntax of the ORDER BY clause, see "SELECT" in Chapter 2: 
"SQL Statement and Eunction Reference." 


Specifying Coiiation Order in a GROUP BY Ciause 

When CHAR or VARCHAR columns are grouped in a SELECT statement, it can 
be necessary to specify a collation order for the grouping, especially if columns 
used for grouping use different collation orders. 

To specify the collation order to use for grouping columns in the GROUP BY 
clause, include a COLLATE clause after the column name. Eor example, in the 
following GROUP BY clause, the collation order for two columns is specified: 

GROUP BY LNAME COLLATE FR_CA, FNAME COLLATE FR_CA; 

Eor the complete syntax of the GROUP BY clause, see "SELEGT" in Chapter 2: 
"SQL Statement and Eunction Reference." 
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Index 

Symbols 

; (semicolon), terminator 130 

A 

access privileges See security 
active set (cursors) 104 
adding 

See also inserting 
columns 19 
integrity constraints 19 
secondary files 13 
aggregate functions 10 
AVG() 25 
COUNTO 35 
MAX() 102 
MIN() 103 
SUMO 123 

ALTER DATABASE 13 

ALTER DOMAIN 15 

ALTER EXCEPTION 16 

ALTER INDEX 17 

ALTER PROCEDURE 18 

ALTER TABLE 19 

ALTER TRIGGER 23 

applications, preprocessing See gpre 

arithmetic functions See aggregate functions 

arrays 

See also error status array 
viewing dimension information 194 
assigning values to variables 131 
assignment statements 131 
averages 24 
AVG() 24 

B 

BASED ON 25 
BEGIN ... END block 
defined 130,131 
exiting 136 

BEGIN DECLARE SECTION 27 
binary large objects See BLOB 


BLOB cursors 
closing 29 
declaring 70 
inserting data 101 
opening 105 
BLOB data 

converting subt 5 ^es 73 
inserting 71,101 
selecting 71 
updating 125 
BLOB data t 5 ^e 217 
BLOB filters 
declaring 72 
dropping 82 

viewing information about 198 
BLOB segments 

host-language variables 26 
retrieving 95 

c 

CACHE option 33 
cache size, changing 33 
case 

converting 126 
nomenclature 4 
CAST() 27 
casting 28 

CHAR data t 5 ^e 217 
CHARACTER SET 
default 37 
domains 40 
specifying 118 
tables 57 

character sets 217-225 
additional 222 
default 222 
retrieving 222 
specifying 222-224 
table of 218 

character strings, converting case 126 
CHECK constraints 58 

viewing information about 191,215 
CHECK_CONSTRAINTS system view 215 
clients See SQL client applications; Windows 
clients 
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CLOSE 28 
CLOSE (BLOB) 29 
code lines, terminating 130 
code pages (MS-DOS) 221 
COLLATE clause 
domains 40 
tables 57 

collation orders 217 
retrieving 222 
specifying 57,224-225 
viewing information about 191 
column names, nomenclature 4 
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adding 19 
computed 57 
defining 38, 57 
domain-based 57 
dropping 19 
formatting 199 
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inheritable characteristics 40 
local 57 

specifying character sets 223 
viewing characteristics of 195,199,206 
comments in stored procedures and 
triggers 132 
COMMIT 30 

compound statements 130 
computed columns 57 
conditional statements 139,149 
conditions, testing 139,149 
See also search conditions 
CONNECT 31 
connecting to databases 31 
constraints 

See also specific t 5 ^e 
adding 19, 57 
dropping 19 
naming 4 
t5^es 58 

viewing information about 205,206,214, 
215,216 

CONSTRAINTS_COLUMN_USAGE system 
view 215 

context variables 140-142 


conversion functions 10 
CAST() 27 
UPPERO 126 
converting data t 5 ^es 27 
COUNTO 34 
CREATE DATABASE 35 
CREATE DOMAIN 38 
CREATE EXCEPTION 41 
CREATE GENERATOR 43 
CREATE INDEX 44 
CREATE PROCEDURE 45,129-130 
CREATE SHADOW 52 
CREATE TABLE 54 
CREATE TRIGGER 60,129-130 
GREATE VIEW 66 
creating multi-file databases 14 
cursors 

active set 104 
closing 28 
declaring 69 
opening 104 
retrieving data 93 
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data 

inserting 99 
retrieving 93 
selecting 110 

stored procedures and triggers 144 
sorting 217 
storing 217 
updating 124 
data integrity 

adding constraints 19, 57 
dropping constraints 19 
data t 5 ^es 11 
converting 27 
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decreasing 33 

database handles, declaring 116 
database objects 
naming 4 

viewing relationships among 193 
database pages 36 
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228 



databases 

altering 13 
connecting to 31 
creating 35 
declaring scope of 117 
detaching 79 
dropping 80 
multi-file 14 

setting access to in SQL 115 
shadowing 52, 84 
viewing information about 216 
dBASE for DOS 221 
dBASE for Windows 221 
DECLARE CURSOR 12, 69 
DECLARE CURSOR (BLOB) 70 
DECLARE EXTERNAL EUNCTION 71 
DECLARE EILTER 72 
DECLARE STATEMENT 12, 74 
DECLARE TABLE 12,58,74 
DECLARE VARIABLE 133 
declaring 

database handles 116 
error status array 157 
host-language variables 25-27, 87 
local variables 133 
scope of databases 117 
SQL statements 74 
SQLCODE variable 27 
tables 74 

default character set 222 
default transactions 122 
defining 

columns 38, 57 
domains 39-40 
integrity constraints 57 
DELETE 75,141 

WHERE clause requirement 76 
deleting See dropping 
DESCRIBE 77 
directories, path names 4, 5 
DISCONNECT 79 
domain-based columns 57 
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altering 15 
creating 38 


defining 39-40 
dropping 80 

inheritable characteristics 40 
DROP DATABASE 80 
DROP DOMAIN 80 
DROP EXCEPTION 81 
DROP EXTERNAL EUNCTION 81 
DROP EILTER 82 
DROP INDEX 83 
DROP PROCEDURE 84 
DROP SHADOW 84 
DROP TABLE 85 
DROP TRIGGER 86 
DROP VIEW 86 
dropping 

columns 19 
integrity constraints 19 
rows 75 

DSQL statements 106-107 

declaring table structures 74 
executing 89, 90, 91 
preparing 105 

E 

-either_case switch 106 
END DEGLARE SEGTION 87 
error status array 157 
declaring 157 
defined 156 
error codes 173-187 
SQLCODE variable 

error codes and messages 160-172 
error-handling routines 12-13,155-159 
isql 12 
options 158 
stored procedures 146 
triggers 146 
errors 

run-time 155 
trapping 126,147,156 
user-defined See exceptions 
EVENT INIT 87 
EVENT WAIT 88 
events 

See also triggers 
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posting 143 

registering interest in 87 
EXCEPTION 134 
exceptions 41 
altering 16 
creating 42 
defined 134 
dropping 81 

viewing information about 194 
EXECUTE 89 

EXECUTE IMMEDIATE 91 
EXECUTE PROCEDURE 92,135 
EXIT 136 

expression-based columns See computed 
columns 

EXTERNAL EILE option 58 

F 

EETCH 93 
EETCH(BLOB) 95 
file names, nomenclature 4-5 
files 

log 203 

secondary 13,198 
shadow 198 
filespec parameter 5 
EOR SELECT ... DO 138 
EOREIGN KEY constraints 58 

viewing information about 215 
formatting columns 199 
functions 10 
aggregate 10 
arguments 199 
conversion 10, 27,126 
numeric 11, 96 
user-defined See UDEs 

G 

GEN_ID() 96 
generators 
creating 43 
initializing 117 
resetting, caution 118 
returning 97 

viewing information about 201 


gpre 87 

declaring SQLGODE automatically 27 
-either_case switch 106 
error status array processing 157 
-manual switch 79,122 
gpre directives 
BASED ON 26 

BEGIN DEGLARE SEGTION 27 
DEGLARE TABLE 74 
END DEGLARE SEGTION 87 
GRANT 97 


host-language variables, declaring 25-27, 87 


I/O See input, output 
identifiers, user-defined 151 
IE ... THEN ... ELSE 139 
indexes 

activating/deactivating 17 
altering 17 

columns comprising 201 
creating 44 
dropping 83 
rebalancing 17 
recomputing selectivity 120 
viewing structures of 202 
indicator variables 93 
initializing generators 117 
input parameters, defined 46,140 
input statements 78 
INSERT 99,140 
INSERT GURSOR (BLOB) 101 
inserting 

See also adding 
new rows 99 
integrity constraints 
See also specific t 5 ^e 
adding 19, 57 
dropping 19 
naming 4 
t5^es 58 

viewing information about 205,206,214, 
215,216 
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Interactive SQL See isql 
international character sets 217-225 
additional 222 
default 222 
specifying 222-224 
isc_convert_error 158 
isc_deadlock 158 
isc_integ_fail 158 
isc_lock_conflict 158 
isc_no_dup 158 
isc_not_valid 158 
isc_print_sqlerror() 157 
isc_sql_interprete() 157 
isc_status 157 
ISOLATION LEVEL 122 
isql 

error handling 12 
statements, terminating 130 

K 

key constraints See EOREIGN KEY constraints; 

PRIMARY KEY constraints 
keys, defined 58 
ke5rwords 151-153 

L 

local columns 57 
local variables 

assigning values 131 
declaring 133 

log files, viewing information about 203 
loops See repetitive statements 
lowercase, converting from 126 

M 

-manual switch 79,122 
MAX() 102 
maximum values 102 
metadata 189 
MIN() 103 
minimum values 103 
modifying See altering; updating 
MS-DOS code pages 221 
multi-file databases, creating 14 
multi-file specifications 5 


multiple transactions, running 122 

N 

naming nodes 4, 5 
naming conventions 4-5 
ke 5 rwords and 151 
nested stored procedures 135 
NEW context variables 140-141 
NO RECORD_VERSION 122 
NO WAIT 122 
nodes, naming 4,5 
nomenclature 4-5 
ke 5 rwords and 151 
stored procedures and triggers 130 
numbers 

averaging 24 
calculating totals 123 
numeric function 11, 96 
numeric values See values 

o 

OLD context variables 141 
OPEN 104 
OPEN (BLOB) 105 
output, error messages 157 
output parameters 46 
defined 142 
output statements 77 

P 

Paradox for DOS 221 
Paradox for Windows 221,222 
parameters 

DSQL statements 77 
filespec 5 
input 46,140 
output 46,142 
stored procedures 204 
path names 4, 5 
platforms 4 
POST_EVENT 143 
posting events 143 
PREPARE 105 
preprocessor See gpre 
primary file specifications 4, 5 


231 






primary files 36 

PRIMARY KEY constraints 43, 58 
viewing information about 215 
printing conventions (documentation) 2-3 
privileges See security 
procedures See stored procedures 

R 

RDB$CHARACTER_SETS 190 
RDB$CHECK_CONSTRAINTS 191 
RDB$COLLATIONS 191 
RDB$DATABASE 192 
RDB$DEPENDENCIES 193 
RDB$EXCEPTIONS 194 
RDB$PIELD_DIMENSIONS 194 
RDB$PIELDS 195 
RDB$PILES 198 
RDB$PILTERS 198 
RDB$PORMATS 199 
RDB$PUNCTION_ARGUMENTS 199 
RDB$PUNCTIONS 200 
RDB$GENERATORS 201 
RDB$INDEX_SEGMENTS 201 
RDB$INDIGES 202 
RDB$LOG_PILES 203 
RDB$PAGES 203 

RDB$PROGEDURE_PARAMETERS 204 
RDB$PROGEDURES 204 
RDB$REP_GONSTRAINTS 205 
RDB$RELATION_GONSTRAINTS 206 
RDB$RELATION_PIELDS 206 
RDB$RELATIONS 208 
RDB$SEGURITY_GLASSES 210 
RDB$TRANSAGTIONS 210 
RDB$TRIGGER_MESSAGES 211 
RDB$TRIGGERS 211 
RDB$TYPES 212 
RDB$USER_PRIVILEGES 213 
RDB$VIEW_RELATIONS 214 
READ GOMMITTED 122 
read-only transactions, committing 30 
read-only views 67 
REGORD_VERSION 122 
recursive stored procedures 135 
REEERENGES constraint 58 


referential integrity See integrity constraints 
REEERENTIAL_GONSTRAINTS system 
view 215 

RELEASE argument 31 
repetitive statements 138,149 
repetitive tasks 135 
reserved words See ke 5 rwords 
RESERVING clause 122 
restrictions, nomenclature 4 
retrieving data 93 
REVOKE 107 
ROLLBAGK 109 
rows 

deleting 75 
inserting 99 
selecting 93 

stored procedures and triggers 144 
sequentially accessing 94 
updating 124 
run-time errors 155 

s 

search conditions (queries) 
comparing values 114,144 
evaluating 104 

secondary file specifications 4,5 
secondary files 36 
adding 13 

viewing information about 198 
secondary storage devices 52 
security 

access control lists, viewing information 
about 210 
access privileges 98 
granting 97 
revoking 107 
viewing 213 
SELEGT 110,144 
selecting data 110-114 

stored procedures and triggers 144 
semicolon (;), terminator 130 
SET DATABASE 115 
SET GENERATOR 117 
SET NAMES 118,223 
SET STATISTIGS 120 
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SET TRANSACTION 121 
shadow files 
sets 53 

viewing information about 198 
shadows 

creating 52 
dropping 84 

SNAPSHOT TABLE STABILITY 122 
sorting data 217 

specifying collation orders 57, 224-225 
SQL clients, specifying character sets 223 
SQL statements 9 
declaring 74 
executing 12 

SQLCQDE variable 12,155-157 
declaring automatically 27 
error codes and messages 160-172 
return values 12 
statements 130 

See also DSQL statements; SQL statements 

assignment 131 

compound 130 

conditional 139,149 

example, printing conventions 3 

executing 105 

input/output 77 

repetitive 138,149 

SQLCQDE and 12 

terminating 130 

status array See error status array 
storage devices, secondary 52 
stored procedures 

adding comments 132 
altering 18 
assigning values 131 
creating 45,129-130 
dropping 84 
error handling 146 
executing 92,135 
exiting 136 
indicator variables 93 
nested 135 
passing values to 140 
posting events 143 
powerful SQL extensions 129 


recursive 135 
terminating 147 

viewing information about 194,204 
storing data 217 
strings See character strings 
SUMO 123 
SUSPEND 145 
S5mtax 

file name specifications 5 
statements, printing conventions 3 
system tables 189-214 
system views 214-216 


table names, nomenclature 4 
TABLE_CQNSTRAINTS system view 216 
tables 

altering 19 
caution 22 
creating 54 
declaring 74 
dropping 85 
inserting rows 99 

viewing information about 206,208,216 
tasks, repetitive 135 
terminators (s 5 mtax) 130 
text 217 

totals, calculating 123 
transaction names 121 
transactions 

committing 30 
default 122 

multiple databases 210 
read-only 30 
rolling back 109 
running multiple 90,91,122 
starting 121 
trapping 

errors 126,147,156 
warnings 126,156 
triggers 131 
altering 23 
creating 60,129-130 
dropping 86 
error handling 146 
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message information 211 

NEW values 140-141 

OLD values 141 

posting events 143 

viewing information about 194,211 


DDEs 200 

declaring 71 
dropping 81 
UNION operator 144 
UNIQUE constraints, viewing information 
about 215 
UNIQUE keys 58 
UPDATE 124,140,141 
updating 

BLQBdata 125 
rows 124 
UPPERO 126 

uppercase, converting to 126 
user-defined errors See exceptions 
user-defined functions See UDEs 
user-defined identifiers 151 
USING clause 123 

V 

values 

See also NULL values 
assigning to variables 131 
averages 24 
changing 140 


maximum 102 
minimum 103 

passing to stored procedures 140 
returning 142,145 

to SQLCQDE variable 12 
totals 123 

VARCHAR data type 217 
variables 

context 140-142 
host-language 25-27, 87 
indicator 93 
local 131,133 
views 

creating 66 
dropping 86 
naming 4 
read-only 67 
updatable 67 

viewing characteristics of 208 

w 

WAIT 122 
warnings 

See also errors 
trapping 126,156 
WHEN 42 
WHEN ... DQ 146 
WHENEVER 126,156 
WHERE clause See SELECT 
WHILE ... DQ 149 

Windows applications, character sets 221 
Windows clients, specifying character sets 223 
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